Introduction

This book documents the current Lapis Notes architecture as implemented in this monorepo on 19 April 2026. It is a current-state description, not a future-state design.

The repository is organized around four primary layers:

• a browser-first workspace shell in packages/workspace
• an Obsidian-like runtime and compatibility layer in packages/api
• a shared Svelte UI kit in packages/ui
• several feature and plugin packages in packages/plugins

Use this spec to understand where behavior lives today, trace boot and data flows, and capture follow-up decisions as ADRs.

Where the codebase is incomplete or ambiguous, the pages call that out directly. The current desktop packaging is one example: checked-in build artifacts exist, but the source package shape is not yet fully represented in the workspace metadata.

Intent

This spec exists to make the current codebase legible before the next round of feature and platform work.

Its goals are:

1. document the package boundaries in the monorepo
2. explain runtime ownership for app state, workspace state, storage, configuration, metadata, and plugins
3. describe how the shipped workspace is assembled from shared packages and feature plugins
4. create a home for ADRs so future architectural decisions have context

This spec is not trying to be a full API reference for every export in @lapis-notes/api, nor a user manual for product features. It is an architecture and implementation map for contributors.

Glossary

System Overview

Lapis Notes is a layered Svelte application that reproduces a large part of the Obsidian runtime model across shared web and desktop hosts. The current source tree is browser-first, and the approved product targets are a web/PWA host and an Electron desktop host. The key design choice is that the workspace app does not own most domain behavior; it mounts the renderer shell, creates the root App instance, and delegates to runtime services and plugins.

The decision to adopt Electron as the first-party native desktop shell is recorded in ADR-003: Electron-First Desktop Shell.

Layer Diagram

user input
  → host shell (web/PWA or Electron desktop)
     → @lapis-notes/workspace (renderer shell)
        → @lapis-notes/api (runtime kernel)
           → Vault, Workspace, Configuration, Commands, Metadata, Plugins
        → @lapis-notes/ui (design system)
        → packaged feature plugins (markdown, search, bases, ...)
        → community plugins from /.obsidian/plugins

The approved cross-runtime plugin direction is recorded in ADR-001: Plugin Runtime Rework (desktop runtime target superseded in part by ADR-003).

Layers

Technology Stack

Architectural Principles

1. App owns services. The App class is the single root that constructs and holds the workspace, vault, plugin manager, commands, configuration, metadata cache, and all registries.

2. Plugins are first-class. Built-in features and community plugins use the same Plugin base class, runtime states, and PluginManager. Core plugins are registered before discovery, then activated through the same manager as community plugins.

3. File-first data flow. Storage updates propagate into metadata indexing, then into higher-level features like search and views. The vault is the source of truth.

4. Event-driven. Almost all classes extend EventDispatcher (wrapping EventEmitter3). Changes propagate via typed events rather than direct mutation observers.

5. Adapter-driven storage. OPFS is the default for new browser-local vaults. File System Access API covers user-selected real folders in web runtimes. Native hosts can add adapters without rewriting the runtime kernel.

6. Thin shells. The workspace app is composition code. Host shells stage the runtime, render the layout, and delegate domain behavior to the API layer and plugins.

7. Obsidian compatibility. The API surface intentionally mirrors Obsidian’s plugin API. compat.ts, parity tests, and the moment shim maintain upstream compatibility. Community plugins can require('obsidian') and get @lapis-notes/api.

Monorepo Structure

The workspace is a pnpm monorepo. pnpm-workspace.yaml includes both packages/* and packages/plugins/*, so the nested plugin packages participate in local workspace resolution.

Important split in the repo

There are two plugin ecosystems present at once:

1. first-party plugins built against @lapis-notes/api
2. colocated plugins that still target the upstream obsidian package directly

That split is important because only the first group participates in the current workspace app boot sequence.

The approved host targets are web/PWA and Electron desktop. The source tree represents the shared browser renderer, the installable web/PWA host, and the first-party Electron desktop shell. See Desktop Host, Desktop Electron Package, and ADR-003: Electron-First Desktop Shell for the authoritative desktop-host direction.

Licensing Model

The repository is multi-licensed. The root LICENSE.md summarizes the current package categories, and each workspace package declares its SPDX license in package.json.

Third-party dependencies and vendored files keep their own notices. File-level notices take precedence for the files they cover.

Runtime Boot Sequence

The current source-visible browser/PWA boot path starts in packages/web/src/main.ts and progresses through host registration, vault selection, app construction, and sequential service initialization for the shared renderer shell. packages/workspace/src/main.ts remains a thin dev-shell entry that calls the same shared bootstrap helper.

Phase 1 — Host Entry Point (packages/web/src/main.ts)

1. Calls mountWorkspaceApp() from packages/workspace/src/lib/components/app/bootstrap.ts to mount VaultBootstrap.svelte to DOM element #app.
2. Loads the shared renderer imports through that bootstrap helper: web fonts, app CSS, bundled core plugins, and buffered bootstrap timing measurements. External official plugins are not imported by the default workspace bundle.
3. Registers browser/PWA host behavior by calling registerWebPwa(), which wires service-worker registration, install-prompt handling, and simple host-level installed/offline-ready state markers.

At build time, packages/web/vite.config.ts also adds the web app manifest, icons, cross-origin-isolation headers, and a generated service worker that precaches the built asset graph for offline startup. The host raises Workbox’s per-file precache limit to 50 MiB so large browser runtime bundles such as SQLite, DuckDB, PDFium, and notebook assets stay inside the offline shell instead of silently dropping out of precache.

Notebook is an external official plugin in this phase. The default workspace bundle does not import notebook code; .notebook.md files route through the official on-demand install flow or an already installed lapis-notebook handler.

The approved hybrid-search direction follows the same rule: the bundled search plugin may register views and commands during boot, but SQLite vector search, local embedding model initialization, and background indexing remain behind the app-database worker and must not make renderer startup pay the cold model-load cost.

Phase 2 — Vault Bootstrap (VaultBootstrap.svelte)

A state machine with six phases:

The vault adapter and app database resolution step is deliberately outside App construction. The File System Access API requires a transient user activation (gesture) to pick or re-authorize a folder, so the shell must present that choice before the runtime starts. Browser bootstrap wraps the result in a VaultSession containing { runtime, profile, vaultAdapter, appDatabase }.

The built-in Open vault command returns to this chooser by clearing the stored current vault profile and reloading the browser shell.

Vault bootstrap also records timing measurements for profile restore, profile opening, and createVaultSession() so delays that happen before App.svelte mounts show up alongside the later task-runner spans.

For browser/PWA sessions, createVaultSession() prefers a SQLite WASM app database persisted under OPFS only when the browser exposes OPFS and the host is cross-origin isolated (SharedArrayBuffer + Atomics available under COOP/COEP). The browser shell now coordinates SQLite ownership per vault before it mounts App.svelte: it takes a Web Lock named from the vault id and resolves whether the tab will be an owner, proxy, or blocked session, but it defers the expensive appDatabase.open() work until the mounted shell begins background metadata hydration. Competing tabs no longer silently switch to a second generated-state store. Instead, when BroadcastChannel is available, the secondary tab receives a coordinated AppDatabase proxy that forwards requests to the owner tab over a per-vault RPC channel while it waits to take ownership later. The blocked shell state remains as a narrow fallback only when delegation is unavailable. IndexedDB fallback remains the compatibility path when Web Locks are unavailable, when OPFS / cross-origin-isolation prerequisites are missing, or when the eventual owner still fails SQLite WASM / OPFS startup and falls back during open(). The browser SQLite runtime is hosted behind a dedicated worker, so App.svelte and the rest of the UI talk to the app database through an async message boundary instead of executing SQLite directly on the UI thread. A future desktop host may short-circuit parts of this UI, but it must preserve the same phase ordering once control passes into App.svelte.

Phase 3 — App Construction (App.svelte)

1. setApplicationState(app) constructs the root App instance from @lapis-notes/api and injects it into Svelte context. New boot paths pass a VaultSession; compatibility paths may still pass only a DataAdapter.
2. Registers shared configuration schemas (appearance, editor).
3. Registers the default "empty" view type.
4. Installs a browser telemetry controller on app.telemetry, including OpenTelemetry span creation plus web-vitals and longtask observers when enabled. The controller keeps a stable app.telemetry reference while allowing the external official lapis-telemetry plugin, when installed and enabled, to override and persist its configuration through the Core plugins settings flow after activation, and it can optionally restore the diagnostics buffer from vault-scoped IndexedDB before the diagnostics view opens.
5. Sets up watchers: color scheme, vault events, metadata tracking.

Phase 4 — Sequential Task Runner

A TaskRunner executes startup tasks in strict order:

During plugin registration and later runtime configuration updates, the plugin manager also mirrors canonical app.json pluginData entries back into the legacy Obsidian plugin settings files so the compatibility layout stays current even when app.json changes externally.

Each step displays a progress message via the TaskRunner.message reactive property. The loading screen also renders the ordered task list with the active step highlighted so startup no longer appears as a single generic spinner label.

If a boot task throws, App.svelte now switches from the loading spinner to an explicit startup-failure surface that shows the failing step, the error detail, and recovery actions such as reload, session-scoped Safe Mode entry, generated-state rebuilds, and targeted plugin disable. The layout step also carries an explicit timeout (currently 20 seconds) so a stalled restore no longer looks like a perpetual Loading layout message.

Safe Mode is intentionally session-scoped. The recovery surface writes a temporary policy record into browser session storage, reloads, and lets the next boot skip specific risky startup work such as configured community-plugin activation, layout restore, or notebook execution. Once the user restarts normally, those temporary flags are cleared instead of becoming persistent vault configuration.

Bundled plugin activation is still synchronous at this phase, but heavyweight plugin internals may defer their own execution transports until first use. External official plugins such as Notebook, Canvas, Graph, Markdown Lint, PDF, Slides, and Telemetry activate only after installation and explicit enablement.

The shell wraps the overall task runner in app.boot and each startup step in app.boot.task spans so regressions can be attributed to a specific initialization phase. Slow spans automatically enrich themselves with workspace and plugin snapshot attributes before export or debug logging.

When App.svelte attaches telemetry, it first flushes the earlier bootstrap measurements from the shared app bootstrap helper and VaultBootstrap.svelte, then starts the existing app.boot and app.boot.task spans for the sequential runner itself.

Phase 5 — Workspace Rendering

After the task runner completes:

1. Keyboard event handler installed: forwards keydown to active leaf’s scope, records app.lastEvent.
2. Console logger registered only when window.__LAPIS_CONSOLE_LOGGING__ or localStorage["lapis.logging.console"] explicitly enables it.
3. Schedules background metadata hydration on the next animation frame after the shell mounts. app.metadataCache.load() opens AppDatabase, restores the cached metadata snapshot from the app database when available, falls back to the legacy browser snapshot when needed, and degrades to an empty in-memory cache when delegated proxy reads time out.
4. Renders the visible workspace:
   • Sidebar.Root — Three-column layout (ribbon + left dock, center split, right dock).
   • Commands — Global command palette (Cmd+P / Ctrl+P).
   • StatusBar — Bottom status bar (plugins inject content here). When the session is using delegated SQLite ownership, the shell also renders a built-in icon-only DB Proxy button that opens a short explanatory popover on click, and removes it once the coordinated database promotes that tab to local SQLite ownership.
   • Tooltip — Global tooltip handler observing data-tooltip attributes via MutationObserver (500 ms default delay).
   • ModeWatcher — Dark/light theme synchronization.
   • Toaster — Toast notification container.
5. Shell teardown disposes the telemetry service so browser performance observers do not linger across app unmounts.

Ordering Implications

• Shell before metadata: Layout and plugins can exist before metadata is fully ready. Metadata-driven features must tolerate boot-time lag and respond to the later metadataCache.loaded event.
• Plugins before layout: Bundled plugins and configured external plugins complete activation before layout restoration. This ensures restored leaves can find their view constructors when the owning plugin is installed and enabled.
• Lazy app-database open: The app database opens on the first post-mount generated-state consumer, normally background metadata hydration. It still stores generated per-vault metadata and search state separately from canonical files.
• Vault before canonical config/plugins/layout: The file tree must be loaded before configuration (stored in .obsidian/), plugins (loaded from .obsidian/plugins/), and layout.
• Watchers early: Color scheme, vault, and metadata watchers are set up during construction, before the task runner starts, so they catch events from the first task onward.

Plugin Dependency Injection

Before PluginManager activates community plugins, the workspace registers a dependency bag (deps.ts) so dynamically loaded plugin code can require():

• obsidian → @lapis-notes/api
• @codemirror/* → CodeMirror packages
• luxon, zod, clsx, bits-ui

This bridges the local runtime with community-style plugin code that was written for the Obsidian API.

Approved Host Direction

The accepted target architecture adds host-level setup around this sequence, but it does not change the ordering guarantees above. See ADR-001: Plugin Runtime Rework and ADR-003: Electron-First Desktop Shell.

1. Resolve the active runtime (web-pwa or electron-desktop) after vault bootstrap and carry it in VaultSession.
2. Construct any host-specific plugin execution registry before community plugin activation.
3. Preserve the invariant that community plugin activation completes before layout restoration.

The current implementation has the storage/session seam needed for host-specific setup, but does not yet provide the plugin host abstraction. All plugin evaluation still happens inside the active renderer/runtime process.

Desktop Shell

Lapis Notes supports two host shells:

• a web/PWA host built directly from @lapis-notes/workspace
• an Electron desktop host that wraps the same renderer/runtime packages

The decision to adopt Electron as the first-party native desktop shell is recorded in ADR-003: Electron-First Desktop Shell. The approved target architecture for the plugin boundary across those hosts is recorded in ADR-001: Plugin Runtime Rework (desktop runtime target superseded in part by ADR-003) and refined in Community Plugin Host Boundary.

Current state in the repo

• packages/workspace is the shared renderer shell.
• packages/web is the installable browser/PWA host around that shared shell.
• packages/desktop-electron is the first-party Electron desktop host package. It owns Electron app lifecycle, native window behaviour, IPC command handlers, and desktop-only runtime adapters. That host-owned window policy applies to secondary app windows as well as the initial window, so Electron child windows opened through the shared workspace popout path inherit the same shell chrome, preload, and shell-metric configuration as the main window. Those popouts do not boot a second shared runtime; instead, the main app-host window remains the single renderer runtime and focused popout windows route native menu actions and inbound app URLs back through that owner window.

Approved boundary

The accepted shell split is:

1. packages/workspace remains the shared renderer shell across all runtime targets.
2. The Electron desktop shell owns native runtime metadata, native capability bridging, and the future community-plugin host boundary via the Node.js main process.
3. Core domain behavior stays in packages/api, packages/workspace, or first-party plugins unless a concern is truly host-specific.

Plugin host implications

Today, community plugins still execute inside the active renderer/runtime process. The approved direction does not change the on-disk plugin format, but it does move shell-specific isolation and native capability brokering into the host layer:

• web/PWA keeps a constrained renderer-hosted community-plugin path
• Electron desktop gains the stronger host boundary for community plugins via Node.js worker/child-process capabilities

Those runtime-specific behaviors are split into implementation slices on the owning package and contract pages, with Plugin Runtime items summarized in Plugin Runtime.

Shell reference shape

The Electron desktop shell follows a standard Electron + Vite + Svelte pattern:

• a renderer package with a fixed Vite dev port (1421) and static build output
• an Electron main process (src-electron/main.ts) that creates BrowserWindow, registers IPC handlers, and drives native menus
• a context-isolated preload script (src-electron/preload.ts) that exposes the native bridge to the renderer via contextBridge.exposeInMainWorld
• the renderer entry (src/main.ts) reads the preload bridge and calls setNativeDesktopBridge() before calling mountWorkspaceApp()

Lapis borrows this shape while keeping the shared @lapis-notes/workspace renderer bootstrap in place.

API Package (@lapis-notes/api)

The API package is the foundational library that every other package depends on. It defines the runtime services, data structures, view hierarchy, plugin contract, and event system that together form the application kernel.

Source: packages/api/src/lib/

It also owns the shared internal-link formatting helpers that metadata and file-management surfaces use to serialize Obsidian-style vault links from a target path plus source note context, and FileManager routes rename-time backlink rewrites through those same helpers so link updates follow the configured file-link formatting rules for markdown notes and other vault files. MetadataCache resolves those short link paths back to markdown notes and other vault files, including bare filenames and unique suffix paths for embeds.

FileManager.processFrontMatter() also preserves unrelated keys when callers mutate frontmatter before metadata indexing has populated a cache entry by seeding writes from parsed file content instead of rewriting from an empty cache object.

The package also maintains a curated docs-only export surface at packages/api/src/lib/docs-api.ts for the public lapis.md TypeScript API reference. Public TSDoc on that surface is the source of truth for generated summaries, parameter descriptions, and return descriptions published under /developers/api-reference/.

App — Central Service Container

The App class (in context.svelte.ts) owns every runtime service. It is the single root object that plugins, views, and the workspace shell receive.

Plugin Distribution Contracts

The API package exposes plugin-distribution primitives for the Full Registry V1 installer path. This module is the shared contract surface for registry metadata, .lapis-plugin bundles, signed release manifests, installed provenance state, canonical JSON, SHA-256 verification, Ed25519 signature verification, DEFLATE-capable bundle extraction, compatibility checks, safe plugin release paths, and reserved plugin-id policy.

The distribution layer treats official status as verified external provenance, not as plugin-controlled manifest content. Manifests loaded from .obsidian/plugins/<plugin-id>/manifest.json therefore remain community-style runtime inputs unless a verified installer records official provenance in .obsidian/installed-plugins.json.

The official registry client remains separate from PluginManager. It fetches signed index and detail metadata from a locked registry source, verifies inline Ed25519 signatures with embedded trusted keys, normalizes relative metadata URLs against the registry index URL, rejects reserved-id policy violations, and can serve a stale adapter-backed cache from .obsidian/plugin-registry-cache.json when network refresh fails. It also fetches and verifies the signed revoked.json policy document for official sources and caches revocation state beside catalog metadata.

Verified installation is also owned by the distribution module rather than the runtime plugin manager. The installer downloads one official .lapis-plugin bundle, verifies the catalog bundle SHA-256 and size, extracts release.signed.json, verifies the signed release manifest, checks every embedded file’s path, size, and SHA-256 hash, rejects unsigned extra bundled files and manifest ID/version mismatches, stages files under .obsidian/plugins/.installing/, swaps them into the Obsidian-compatible plugin folder, and records provenance in .obsidian/installed-plugins.json. Manual installBundle() uses the same verified official bundle path for a local .lapis-plugin file. Bundle entries may be stored or DEFLATE-compressed; the signed release manifest remains stored as the first archive entry. The default distribution manager selects bundleVerification: "auto" for web installs, which verifies bundle hash/size, signature, and signed files in a module worker when available and falls back to the main-thread verifier. Tests and non-web hosts can force bundleVerification: "main-thread". Progress events include verifying-bundle before signed-file verification, and extraction, verification, and staging report processed byte/file progress when available. Fresh registry installs and manual .lapis-plugin installs enable the plugin by default when a plugin manager is present; update paths pass the previous enabled state explicitly so disabled plugins stay disabled. Uninstall removes plugin code and the enabled community-plugin entry while preserving data.json by default. Install and update operations accept a cooperative AbortSignal and emit phase-based progress events. Bundle downloads report aggregate byte progress when the response stream or fallback body size is available, so callers can surface determinate status-bar progress without weakening signature, size, or hash verification.

The distribution layer also validates signed runtime metadata for official ESM-only external releases before staging. It compares signed release runtime metadata with packaged manifest.json Lapis entries, rejects official CommonJS entries and fallbackPath, checks module-format file extensions, scans entry sources for bare imports, and validates declared or scanned shared dependencies against the generated host-module catalogue. Official failures are hard install errors; manual and community compatibility paths can retain CommonJS/fallback metadata and surface the same diagnostics as warnings on installed provenance records.

PluginDistributionManager applies verified revocation policy to installed official records, lists compatible updates, surfaces incompatible latest releases with compatibility reasons, and treats revoked installed versions as a distinct state that can be disabled or updated to a compatible replacement. Verified updates reuse the same staged installer path as fresh installs and preserve the plugin’s enabled state when the runtime reports it as enabled. Update progress and cancellation use the same installer signal and progress event contract as fresh installs.

The package also owns the loader-side contracts used by the structured ESM/CommonJS transition. lapis-extension.ts accepts structured lapis.runtime.entries metadata beside the legacy runtime strings, plugin-runtime-entry.ts contains the shared selector for workspace, Electron renderer, and Electron sidecar entry choice, plugin-dependency-resolver.ts defines the shared dependency resolver seam, and plugin-dependency-scanner.ts provides conservative runtime diagnostics for bare require, import, dynamic import(), and re-export specifiers. Generated host-module registry metadata under src/lib/generated/ is consumed by diagnostics and distribution validation so the app does not maintain a second dependency allowlist.

plugin-asset-server.ts defines the plugin module URL shapes used by renderer ESM loading, including hash-bearing /__lapis/plugins/... routes for web/PWA and lapis-plugin://... URLs for Electron renderer, plus path normalization, MIME type selection, and installed-file size/hash verification helpers. The package does not serve those URLs itself; host-specific asset serving remains owned by the web and Electron packages. When a host provides PluginAssetServer, PluginManager uses a hybrid execution host that imports structured ESM entries from verified module URLs, keeps CommonJS and sidecar entries on their existing hosts, and falls back to CommonJS only when the ESM descriptor declares fallbackPath. Community plugin diagnostics include the selected host and module format, fallback entry and fallback-used status, reload-on-update policy, asset URL mode and URL, declared/scanned shared dependencies, undeclared and missing shared dependencies, plus deprecated and private host-module usage.

Properties

Browser vault sessions now resolve coordinated SQLite ownership before App construction, but defer the actual appDatabase.open() work until the mounted workspace shell begins background metadata hydration so the coordinated database boundary retains SQLite-to-fallback handling without blocking first paint. Desktop sessions use the same VaultSession boundary to resolve a native folder adapter plus a native app database bridge, keeping generated state in host-owned native SQLite storage outside the selected vault while preserving the same AppDatabase contract that browser runtimes use. Saved VaultProfile records may also carry optional demo metadata (source, fixtureVersion) so renderer flows such as the bundled demo workspace can remain identifiable across chooser restores and reset commands; browser OPFS recreation preserves that demo metadata when reopening an existing saved profile. The neutral native desktop bridge also carries host-advertised platform details and a service capability registry for resource, database, search, notebook, model, plugin-sidecar, file-watch, notifications, and file-system action providers. The vault contract exposes async resource URLs with explicit revocation so browser adapters can return blob URLs and native adapters can return host-owned URLs for read-only media surfaces. | markdownPostProcessor | MarkdownPostProcessor[] | Sorted post-processors | | markdownCodeBlockPostProcessor | Record<string, Function> | Language-keyed code processors | | metadataTypeManager | MetadataTypeManager | Frontmatter type tracking | | commands | CommandManager | Command registry and palette | | contextKeys | ContextKeyService | Declarative context-key store and when evaluator | | statusBar | StatusBarManager | Declarative status bar contribution registry with stable-order in-place updates | | urls | AppUrlService | Lapis/Obsidian-style app URL parser, opener, and plugin protocol-handler registry | | metadataCache | MetadataCache | File metadata index | | notifications | NotificationManager | In-app notification records and progress handles | | embedRegistry | EmbedRegistry | Embed view handlers | | lastEvent | Event | Last UI event | | renderContext | MarkdownFileInfo | Markdown render context | | secretStorage | SecretStorage | Encrypted key-value store | | languageServices | LanguageServiceManager | Host-neutral diagnostics, completion, hover, definition, and code-action providers |

Key Methods

StatusBarManager owns the API-side registry used by the workspace shell. Items can be registered declaratively, gated by when expressions against App.contextKeys, and updated in place through upsertItem() without losing their original registration order. That lets first-party contributors such as notifications change text, tooltip, command, icon, and visibility as background state changes while Plugin.addStatusBarItem() remains the raw-DOM compatibility escape hatch.

AppUrlService owns app URL parsing and dispatch. It accepts lapis://open?vault=...&file=..., the existing lapis-notes:// alias, installed-PWA web+lapis:// launches routed through the web host, Obsidian-style vault and absolute-path shorthands, and plugin-registered custom actions. The built-in open action validates that vault-targeted URLs refer to the current vault by id or name, resolves markdown paths with optional .md omission, opens non-markdown files through the normal workspace file-view routing, and keeps custom action handlers reversible through plugin unload.

• openFile(file, opts?) — Opens a file in the workspace by creating or reusing a main-area leaf.
• registerEditorExtension(ext, viewType?) — Adds a CodeMirror extension globally or scoped to a view type.
• registerMarkdownPostProcessor(processor, sortOrder?) — Inserts a post-processor in sorted order.
• registerMarkdownCodeBlockProcessor(language, handler, sortOrder?) — Registers a fenced-code-block renderer.

Notifications And Progress

App owns a host-neutral NotificationManager at app.notifications. The manager is the single runtime API for in-app messages, persisted notification history, and long-running progress. The required bundled notifications plugin owns the visible renderer surfaces; callers do not talk to Svelte, svelte-sonner, browser notification APIs, or desktop host APIs directly.

Public operations:

• notify(options) records an information, warning, or error notification and optionally persists it.
• createProgress(options) creates a progress handle for long-running work.
• withProgress(options, task) creates a progress handle, passes a cooperative cancellation signal/token to the task, and completes or fails the handle when the task settles.
• list(), markRead(id), clear(id), and clearAll() manage the current notification history.

Progress reporting accepts both determinate counters (current / total) and VS Code-style incremental reports (increment, where increments accumulate toward 100). If neither form is available the progress item is indeterminate. Progress handles carry title, source, message, location (status, notification, or silent), cancellability, terminal state, and an AbortSignal for cooperative cancellation. The manager never preempts synchronous plugin code; cancellation is delivered to work that checks the signal between natural async boundaries.

Notification history is generated per-vault app state. Durable notifications are persisted through AppDatabase, while live progress is session state unless the caller asks to persist terminal success or failure. Desktop hosts may mirror selected durable records to native OS notification APIs through the neutral native bridge; the shared app.notifications API remains renderer- and host-neutral.

Context Injection

The App instance is provided to Svelte components via setApplicationState(app) / useApplicationState() using Svelte context, avoiding prop-drilling.

Workspace — Layout and View Management

The Workspace class (in workspace.svelte.ts) manages the split-pane layout, tab groups, leaves, and the view type registry.

Layout Tree

Workspace
├── rootSplit: WorkspaceSplit   (center)
├── leftSplit: WorkspaceSplit   (left sidebar)
└── rightSplit: WorkspaceSplit  (right sidebar)
    └── children: (WorkspaceSplit | WorkspaceTabs)[]
        └── WorkspaceTabs
            └── children: (WorkspaceLeaf | WorkspaceSidebarGroup)[]
                ├── WorkspaceLeaf
                │   └── view: View
                └── WorkspaceSidebarGroup
                    └── children: WorkspaceLeaf[]
                        └── view: View

WorkspaceSplit

Represents a vertical or horizontal partition:

• children: (WorkspaceSplit | WorkspaceTabs)[] — Nested splits or tab groups.
• sizes: number[] — Proportional sizes for resizable panes.
• type: "vertical" | "horizontal" — Split direction.
• parent — Parent split reference.

WorkspaceTabs

A group of tabbed workspace children:

• children: (WorkspaceLeaf | WorkspaceSidebarGroup)[] — Leaves in normal tab groups, and sidebar groups where the tab group belongs to a sidedock.
• currentTab: number — Active tab index (reactive via $state).
• stacked: boolean — Stacked vs. tabbed display mode.
• addLeaf(leaf), removeLeaf(leaf) — Manage children.

WorkspaceSidebarGroup

A sidebar-only container that behaves like a VS Code-style view container while keeping each child as a real WorkspaceLeaf:

• id, name, icon — Stable group identity and display metadata.
• children: WorkspaceLeaf[] — Ordered child leaves mounted as collapsible panels by the workspace shell.
• hiddenLeafIds — Persisted child visibility state; hidden leaves remain in the group.
• collapsed — Persisted per-child collapsed panel state.
• panelSizes — Optional persisted per-child panel proportions used by the workspace shell when grouped sidebar panels are resized.

WorkspaceLeaf

A single pane that hosts a view:

• view: View | null — The currently mounted view.
• containerEl: HTMLElement — DOM container.
• id: string — Unique identifier.
• openFile(file, opts?) — Opens a file using the view type registry. When no registered handler exists, it may mount the plugin-install-prompt fallback for verified official registry matches.
• setViewState(state) — Switches or configures the view.
• getViewState() — Serializes view state for layout persistence.

WorkspaceRibbon

Left-side icon strip. addRibbonIcon(icon, title, callback) adds items.

WorkspaceSidedock

Wraps a WorkspaceSplit with show/hide/collapse semantics for left and right sidebars.

View Type Registry

workspace.registerView(type: string, creator: (leaf) => View)
workspace.registerEditorView(contribution)
workspace.registerSidebarView(type: string, options)
workspace.registerExtensions(exts: string[], viewType: string)

Extensions (e.g., .md or .notebook.md) map to view types. registerEditorView() registers stable editor-view metadata used by settings and association resolution; registerExtensions() also backfills compatibility metadata for older registrations. When a file is opened, the workspace first checks workspace.editorAssociations for matching VS Code-style glob patterns, then falls back to registered editor-view filename patterns, and finally falls back to the longest matching registered suffix. The resolved view type is looked up in the constructor registry and mounted in the leaf.

registerSidebarView(type, options) records default sidebar placement metadata for non-file views. ensureSideLeaf(type, options) can use those defaults, or explicit options such as side, group, groupTitle, groupIcon, and hidden, to create the leaf in a normal sidebar tab or under a WorkspaceSidebarGroup. Plugin.registerSidebarView(type, creator, options) wraps view registration and placement cleanup for plugin-owned sidebar contributions.

Default file navigation targets the root split. workspace.getLeaf(false), workspace.openLinkText(...), and app.openFile(file) reuse the active main-area leaf or selected root tab, and create a root leaf when none exists. They do not reuse an active sidebar leaf; sidebar views are opened through explicit sidebar APIs such as ensureSideLeaf(), getLeftLeaf(), and getRightLeaf().

Layout Persistence

getLayout() → JSON, loadLayout(json), requestSaveLayout() (debounced). The JSON captures the full tree: splits, tabs, leaves, sidebar groups, hidden/collapsed/resized group panel state, and view states. Old flat sidebar tab JSON still loads without group entries, and grouped sidebar JSON without panelSizes falls back to equal panel proportions.

Key Workspace Methods

Hover-Link and Window Compatibility

• registerHoverLinkSource(id, info) stores hover-preview source registrations for plugin compatibility and supports unload cleanup through the plugin lifecycle helpers.
• openPopoutLeaf() and moveLeafToPopout() now route through a host popout capability. Browser and Electron hosts open a separate Window/Document that still renders the shared WorkspaceWindow tree, while unsupported hosts raise an explicit error without detaching the source leaf. Drag-out layout gestures still use the separate in-app floating-pane path.
• Floating WorkspaceWindow entries track normal, collapsed, minimized, and maximized display state. Collapsed and minimized state serialize with the live workspace layout; maximized state is renderer-only and restores as normal after reload.

View Hierarchy

Defined in view.svelte.ts. All views extend the Component base class for lifecycle management.

Component
└── View
    └── ItemView
        └── FileView
            ├── TextFileView
            │   └── MarkdownView
            └── EditableFileView

Component (base)

• children: Component[] — Child lifecycle management.
• containerEl: HTMLElement — Root DOM element.
• loaded: boolean — Lifecycle state.
• load() / unload() — Lifecycle hooks.
• register(cleanup) — Registers teardown callbacks.
• registerEvent(ref) — Auto-cleaned event subscriptions.
• registerDomEvent(el, type, handler) — Auto-cleaned DOM listeners.
• registerInterval(id) — Auto-cleared intervals.

View

Abstract base for all views:

• icon: string — Lucide icon identifier.
• leaf: WorkspaceLeaf — Owning leaf.
• scope?: Scope — Keyboard scope (pushed when leaf is active).
• abstract getViewType(): string
• abstract getDisplayText(): string
• getState() / setState(state) — Serialization for layout persistence.

ItemView

Adds a toolbar actions bar:

• actions: Array<{icon, title, callback}> — Toolbar buttons.
• contentEl: HTMLElement — Read-only content container below the toolbar.
• addAction(icon, title, callback) — Registers a toolbar button.

FileView

Associates a view with a file:

• file: TFile | null — The backing file.
• abstract onLoadFile(file): Promise<void> — Called when a file is loaded.
• abstract onUnloadFile(file): Promise<void> — Called when file is unloaded.
• abstract onRename(file): Promise<void> — Called on file rename.
• abstract canAcceptExtension(ext: string): boolean — Declares supported extensions.

TextFileView

Text editor base backed by CodeMirror 6:

• editor: Editor — CodeMirror wrapper instance.
• data: string — Current document content.
• adapter: DataAdapter — Deprecated compatibility accessor for direct adapter access.
• abstract getViewData(): string, setViewData(data, clear?), clear() — Subclass data hooks.
• save(clear?) — Writes content through app.vault.modify().
• onLoadFile(file) — Reads through app.vault.read(), then sets editor extensions.
• onRename(file) — Updates file reference.

MarkdownView

Extends TextFileView with dual-mode rendering:

• previewMode: MarkdownPreviewView — Preview renderer.
• currentMode: MarkdownSubView — Source / preview / live-preview state.
• hoverPopover: HoverPopover | null — Page hover preview.

EmptyView

Placeholder for new tabs. View type "empty". Mounts EmptyViewComponent with create/open/recent/close actions. Uses localized display text via t("base/empty-view", "New Tab"). When WorkspaceLeaf.setViewState() receives an unsupported view type, the workspace falls back to this view, preserves the original requested type in the view state under state.__missingViewType, and displays that identifier in the empty view title.

Plugin System

Plugin Base Class

Every plugin extends Plugin (which extends Component):

• basePath: string — Plugin folder path.
• manifest: PluginManifest — Parsed manifest.json.
• enabled: boolean — Current state.
• hostMode: string — Community plugin execution host used for diagnostics.
• requestedCapabilities / grantedCapabilities — Runtime capability declarations and broker decisions surfaced for hosted plugin diagnostics.
• lastFailureMessage / failureCount — In-memory diagnostic history across failed enable, disable, and restart attempts.
• app: App — App instance.
• abstract onload(): Promise<void> | void — Initialization hook.
• onunload(): Promise<void> | void — Cleanup hook.
• enable() / disable() — Toggle with "enable" / "disable" event emission.

Baseline Obsidian-style manifests remain valid. External manifests may additionally declare supportedRuntimes, requiredCapabilities, and executionHints; PluginManager treats missing declarations as compatible, but rejects explicit runtime or capability requirements before evaluation when the selected host cannot satisfy them.

External Plugin Diagnostics

PluginManager keeps external plugin diagnostics separately from loaded plugin instances so preflight and evaluation failures remain visible even when no Plugin object could be registered. Diagnostics include plugin ID/name, manifest summary metadata (version, author, and description), source (official or community), provenance, selected host mode, activation mode (code, manifest-only, or not-activated), the selected runtime entry when known, requested capabilities, granted capabilities, lifecycle/preflight state, and the last failure message. Indexed Lapis-extension metadata remains available alongside those diagnostics so the workspace UI can show permission declarations, granted app permissions, and trusted-desktop warnings without depending on a loaded Plugin instance. Runtime-entry preflight also validates that Lapis code entries stay within the plugin root and use supported JavaScript file extensions before evaluation is attempted. The manager exposes the current host ID, a full diagnostics list, per-plugin lookup, and restartPlugin(pluginId) so the workspace UI can retry failed plugins without first removing them from the external enablement configuration.

Registration API

Plugins register functionality during onload():

Suggest Helpers

AbstractInputSuggest, SuggestModal, and FuzzySuggestModal provide the shared Obsidian-style suggestion helpers used by plugins and editor-adjacent UI:

• input/modal suggestion lists refresh from the current query string
• arrow keys move the active item
• Enter and Tab choose the active item
• Escape closes the suggestion UI
• instruction rows render when provided through setInstructions(...)

Plugin Manifest

interface PluginManifest {
  id: string;
  name: string;
  author: string;
  version: string; // semver
  minAppVersion: string; // semver
  description: string;
  dir?: string; // plugin folder in vault
  authorUrl?: string;
  isDesktopOnly?: boolean;
  supportedRuntimes?: string[];
  requiredCapabilities?: HostedPluginCapability[];
  executionHints?: Record<string, unknown>;
  lapis?: LapisExtensionManifest;
}

PluginManager

Owns the full plugin lifecycle. Extends EventDispatcher.

Properties:

• plugins: Map<string, Plugin> — Loaded plugins keyed by ID.
• lapisExtensions: LapisIndexedExtension[] — Manifest-indexed Lapis extensions keyed by discovery, including manifest-only extensions that did not instantiate plugin code.
• dependencies: Record<string, any> — Module dependencies for require() injection.
• pluginsPath: string — "/.obsidian/plugins".
• adapter: DataAdapter — File system.

Lifecycle:

1. loadPlugins() — Ensures the plugin folder exists, reads installed provenance from .obsidian/installed-plugins.json, discovers external plugin manifests, reads community-plugins.json, then activates bundled plugins, configured official plugins, and configured community plugins before emitting "plugins-loaded".
2. loadPlugin(path) — Loads a single external plugin. Parses manifest.json, resolves source/provenance from verified installed state or caller options, validates/classifies optional lapis metadata, indexes Lapis contributions before code evaluation, runs manifest preflight, and evaluates the selected runtime entry when an Obsidian-compatible or hybrid plugin needs code. Multi-file CommonJS plugin builds can use relative require() calls for local .js, .cjs, and .mjs chunks under the plugin folder. Structured ESM entries load through the host-provided plugin asset URL server when available. Manifest-only Lapis extensions may be indexed without a Plugin instance. Emits "plugin-loaded" only for instantiated plugins.
3. enablePlugin(id) — For instantiated plugins, calls plugin.enable(), injects registered bundled core-plugin CSS or reads external styles.css if present, and appends a <style id="plugin-css-{id}"> element to <head>. For manifest-only Lapis extensions, installs declarative commands and configuration schemas without evaluating code and records diagnostics for indexed contribution kinds that are not installable yet. Saves enabled state to community-plugins.json for official/community external plugins or core-plugins.json for bundled/system plugins as appropriate. Emits "plugin-enabled" only for instantiated plugins.
4. disablePlugin(id) — For instantiated plugins, calls plugin.disable() and removes the CSS element. For manifest-only Lapis extensions, disposes manager-installed command/configuration effects. Saves state. Emits "plugin-disabled" only for instantiated plugins.

Dynamic Import:

External plugin JavaScript evaluation runs through CommunityPluginExecutionHost. The default RendererCommunityPluginExecutionHost loads CommonJS chunks as strings, wraps each evaluated module in new Function('exports', 'module', 'require', ...), and executes it in the renderer. The injected renderer require() resolves relative local chunks from the same plugin folder and external modules from the registered dependency resolver. Unknown modules throw an error. When a host supplies PluginAssetServer, PluginManager installs a hybrid execution host: structured ESM entries are imported from version/hash plugin asset URLs, CommonJS entries continue through the CommonJS host, Electron sidecar entries stay delegated to the sidecar host, and ESM-to-CommonJS fallback is attempted only when the selected runtime entry declares fallbackPath. The manager records whether fallback was actually used, the asset URL mode and URL used for renderer ESM imports, and the selected runtime’s reload requirement so the settings UI can explain loader behavior after activation. The native sidecar bridge receives the same selected runtime metadata and wraps sidecar evaluation failures with host, format, and entry context while preserving the original dependency or local-graph diagnostic.

Hosted Plugin Capabilities:

HostedPluginCapabilityFacade defines the initial structured, serializable capability surface for sidecar-hosted community plugins: vault read/write, plugin data, commands, notices, settings reads/surfaces, metadata queries, approved event subscriptions, and logging. The facade forwards every call to a HostedPluginCapabilityBroker request instead of exposing the live renderer App graph, DOM objects, or Node.js primitives.

Events: plugins-loaded, plugin-loaded, plugin-enabled, plugin-disabled, plugin-error, css-change.

Current boundary: PluginManager is still the lifecycle owner. It performs manifest preflight, CSS loading, source/provenance classification, and failure reporting in the active renderer/runtime process. External plugin code evaluation is delegated to the configured execution host; the default renderer host still evaluates CommonJS modules in process.

Approved direction: ADR-001: Plugin Runtime Rework defines the runtime-neutral execution-host and extension-manifest direction. The current implementation now covers classification, Lapis namespace validation, contribution indexing, activation-event lazy loading, generated extension state, manifest-only command/configuration installation, scoped language-service provider registration, bundled or code-backed system-extension registration, and host-selected workspace or trusted-desktop code entry loading with per-plugin Electron-sidecar hardening. The remaining runtime work is limited to richer manifest-only coverage plus follow-on runtime expansion such as browserWorker and multi-host hybrid activation.

Storage — Vault, Session, and App Database

DataAdapter Interface

Compatibility contract for path-based file system operations:

interface DataAdapter {
  getName(): string;
  exists(path): Promise<boolean>;
  stat(path): Promise<Stat | null>; // {type, ctime, mtime, size?}
  read(path): Promise<string>;
  readBinary(path): Promise<ArrayBuffer>;
  write(path, data, opts?): Promise<void>;
  writeBinary(path, data, opts?): Promise<void>;
  append(path, data, opts?): Promise<void>;
  appendBinary(path, data, opts?): Promise<void>;
  process(path, fn: (data) => string, opts?): Promise<string>;
  list(path): Promise<{ files: string[]; folders: string[] }>;
  mkdir(path, opts?): Promise<void>;
  rmdir(path, recursive): Promise<void>;
  remove(path): Promise<void>;
  rename(path, newPath): Promise<void>;
  copy(path, newPath): Promise<void>;
  getResourcePath(path): string; // For <img src>
  trashSystem(path): Promise<boolean>; // OS trash
  trashLocal(path): Promise<void>; // .trash folder
}

VaultAdapter is the preferred storage contract for new runtime work. It extends DataAdapter today and can expose optional capabilities such as persistence, user-visible files, permission requirements, native watching, resource URLs, and system trash support. DataAdapter remains exported for Obsidian-style plugin compatibility and older call sites.

VaultSession

VaultSession groups the runtime-selected storage objects that App needs:

interface VaultSession {
  runtime: "web-pwa" | "electron-desktop" | "test";
  profile?: VaultProfile;
  vaultAdapter: VaultAdapter;
  appDatabase?: AppDatabase;
  appDatabaseState: {
    status: "ready" | "blocked";
    mode:
      | "sqlite-owner"
      | "sqlite-proxy"
      | "sqlite-blocked"
      | "indexeddb-fallback"
      | "memory-fallback";
    lockSupported: boolean;
    message?: string;
  };
  awaitAppDatabase?: (options?: {
    signal?: AbortSignal;
  }) => Promise<VaultSession>;
}

The browser workspace resolves this before constructing App. When a competing tab already owns the per-vault SQLite OPFS database, the preferred browser path now returns a ready session backed by a coordinated proxy AppDatabase that forwards requests to the owner tab over BroadcastChannel and can later promote itself to owner when the lock becomes available. The blocked state remains as a fallback only when delegation cannot be established. Adapter-only construction is still supported for compatibility and tests; in that path App creates a default app database from the adapter’s vault ID.

AppDatabase

AppDatabase stores per-vault generated state separately from canonical vault files. The contract covers schema migration, metadata snapshots, indexed file records, links, tags, properties, search document records, notebook output and scalar input snapshots with per-cell source fingerprints, explicit FTS rebuild support, cheap search-index stats, optional search-index batching for refresh-heavy backends, and snippet-rich search query access with raw lexical/vector scores plus explainable Reciprocal Rank Fusion breakdowns for hybrid retrieval.

MetadataCache.load() opens the app database and restores the app-database snapshot first. If that snapshot is missing, it reads the portable generated backup at .lapis/cache/metadata-cache.json, validates the versioned envelope, applies the snapshot, and hydrates AppDatabase with both the snapshot and per-file indexed metadata records. Legacy ScopedVaultStore metadata snapshots remain a final migration fallback. When no valid state exists, metadata loading runs the first-open rebuild and emits loaded only after that rebuild persists a fresh snapshot and backup.

Current implementations:

• SqliteWasmAppDatabase — SQLite WASM using OPFS persistence for browser/PWA sessions when available. The public class proxies all SQLite execution through a dedicated worker while mirroring app state in the main thread, and search-document upserts now sync the worker-prepared document back into that mirror instead of re-running search preparation on the renderer.
• IndexedDbAppDatabase — browser fallback backed by ScopedVaultStore(vaultId, "app-database").
• MemoryAppDatabase — tests and runtimes without IndexedDB.
• NativeDesktopAppDatabase — native SQLite generated-state contract for the Electron desktop host.

In browser bundles, the SQLite WASM implementation resolves sqlite3.wasm through the package’s exported asset URL so bundlers serve the binary instead of falling through to an HTML route.

The SQLite schema includes schema_meta, files, metadata, links, tags, properties, search_docs, and search_fts. SQLite is not canonical note storage; deleting the app database should only require rebuilding metadata and search from files exposed by the vault adapter. Search queries return document hits plus explicit snippet/range metadata and score explanations so UI layers do not need a separate tokenization/highlight engine. The search contract now also exposes incremental search-index stats plus explicit beginSearchIndexingBatch() / endSearchIndexingBatch() hooks so refresh-heavy backends can batch expensive persistence work. In browser/PWA sessions, SQLite ownership is coordinated per vault with Web Locks and BroadcastChannel heartbeats; only the owner tab starts the SQLite worker, while secondary tabs proxy AppDatabase requests to that owner when delegation is available and fall back to the blocked state only when delegation cannot be established. The shared Transformers.js embedding provider keeps browser-managed Cache API caching in browser/PWA runtimes, but disables that cache path inside native desktop renderers so corrupted persisted Chromium cache state cannot wedge semantic-search initialization.

Browser Adapters

• OpfsVaultAdapter — Origin Private File System. Works offline, no permission prompts. Default for new browser-local vaults.
• BrowserHandleVaultAdapter — File System Access API. Opens user-selected real folders via picker. Requires transient user activation.
• OPFS and File System Access handle-backed browser adapters retry recoverable NotFoundError, NotReadableError, NoModificationAllowedError, InvalidStateError, and ENOENT failures on reads, writes, deletes, and directory listings, and normal writes truncate existing files before replacing their contents.
• getAdapterVaultId(adapter) — Returns a stable identifier for scoped storage.
• ScopedVaultStore(vaultId, scope) — Scoped browser storage still used for vault profiles, legacy metadata fallback, and the IndexedDB app-database fallback.

File Model

TAbstractFile { path, parent, vault, baseName, extension, name }
├── TFile { stat: FileStats {ctime, mtime, size} }
└── TFolder { children: TAbstractFile[], iterateAll(cb) }

TAbstractFile.copy(props) creates a clone with property overrides.

Vault Class

Extends EventDispatcher. Owns the file tree:

• adapter: DataAdapter — Active backend.
• files: Record<string, TAbstractFile> — In-memory file tree cache.
• cache: FileCache — LRU in-memory cache.
• configDir: string — ".obsidian".

File Operations: create, createBinary, createFolder, mkpath (recursive), modify, modifyBinary, process (read-modify-write), delete, trash, rename, copy.

Tree Operations: load, loadPath, reload, getRoot, getAbstractFileByPath, getFileByPath, exists, stat, list.

Events: load, create, modify, delete, rename, all (any event with type discriminator).

DirectoryWatcher

Polls or observes the adapter for changes: watch(path, opts) → {close()}. Events: create, modify, delete, error, all.

Path Utilities

normalizePath, joinPath, splitPath, dirname, basename — all browser-safe, no Node.js dependency.

MetadataCache — File Indexing

The MetadataCache (in cache.svelte.ts) indexes every file’s structural content.

CachedMetadata

interface CachedMetadata {
  frontmatter?: FrontMatterCache;
  frontmatterPosition?: Pos;
  links?: LinkCache[]; // [[wikilinks]]
  embeds?: EmbedCache[]; // ![[embeds]]
  tags?: TagCache[]; // #tags
  headings?: HeadingCache[]; // Headings with level (1-6)
  sections?: SectionCache[]; // Block-level sections
  listItems?: ListItemCache[]; // List items with optional task state
  footnotes?: FootnoteCache[]; // [^ref] footnotes
  blocks?: Record<string, BlockCache>; // ^block-ids
}

Every cache item carries a Pos { start: Loc, end: Loc } where Loc = { line, col, offset }.

Cache Items

Link Resolution

• getFirstLinkpathDest(linkpath, sourcePath) — Resolves [[link]] to a TFile. Tries exact path, .md suffix, .markdown suffix, then basename match.
• resolvedLinks and unresolvedLinks — Adjacency maps: Record<string, Record<string, number>>.
• resolveSubpath(cache, subpath) — Resolves #heading, ^block, [^footnote] references within a file.

Metadata Processors

Plugins register custom MetadataProcessor objects per file extension:

interface MetadataProcessor {
  read(data: string, ctx: { cache; file }): Promise<CachedMetadata>;
  write(cache: CachedMetadata): string;
}

Persistence

Caches are persisted through app.appDatabase keyed by vault ID. File tracking by {mtime, size, hash} is preserved, and parsed metadata is also decomposed into app-database file, link, tag, and property records. Persistence remains debounced at 500 ms. A legacy ScopedVaultStore cache can be read as a migration fallback when no app-database snapshot exists.

Events: changed(file, data, cache), deleted(file, prevCache), loaded.

MetadataTypeManager

Tracks frontmatter property types across all files:

• types: Record<string, MetadataTypeDef> — Persisted to types.json in config folder.
• properties: Record<string, MetadataTypeProperty> — Runtime index with { name, type, count, files: Set<string> }.
• registeredTypeWidgets: Record<string, TypeWidget> — Plugin-provided custom renderers.

Type Inference: Number, Boolean, Tags, Aliases, Date (YYYY-MM-DD), DateTime (ISO 8601), Multitext (primitive arrays), Array, Object, Text (fallback).

Methods: load(), save() (debounced), setType(field, type), registerTypeWidget(widget), getAllProperties(), getValues(key), processChange(file, cache), processDelete(file), trackChanges(), plus exact top-level bulk rename, delete, and type-change helpers used by All Properties. Exact-key bulk helpers preserve literal dotted keys such as note.status instead of treating them as lodash paths.

Editor — CodeMirror 6 Integration

The Editor class (in editor.svelte.ts) wraps a CodeMirror 6 EditorView:

• view: EditorView — CM6 instance.
• file: TFile | null — Backing file.
• extensions: Extension[] — Active extensions.
• id: string — Unique ID (UUID).
• getValue() / setValue(content) — Full document access.
• replaceContent(content) — Efficient partial replace via dispatch.
• getLine(line) — Gets line text.
• somethingSelected() — Has selection?
• save() — Writes to vault (debounced 500 ms).
• refresh() — Requests CM6 measure/layout.
• updateExtensions(extensions?, context?) — Reconfigures CM6 extensions.
• trackChanges(callback?) — Syncs external file changes to the editor; returns unsubscribe.

Events: change(data: string).

The shared NoteEditor renders its inline file title inside the editor scroll area immediately before the .cm-editor-content editor host. Desktop visibility follows appearence.interface.showInlineTitle, while mobile workspace display mode forces the same in-scroll title on so file-backed mobile titles scroll with the document instead of separate shell chrome.

The shared class-based syntax highlighter used by API-owned editors emits the existing CodeMirror cm-* token classes together with compatible hljs-* token classes for tags that map cleanly onto the bundled highlight.js theme vocabulary. This lets non-markdown editors reuse highlight.js token styling without dropping the existing CodeMirror selectors.

CM6 State Fields

State fields make app context available inside extensions:

• editorViewField: StateField<MarkdownFileInfo> — { app, file, editor }.
• editorEditorField: StateField<EditorView> — Editor instance.
• editorLivePreviewField: StateField<boolean> — Live preview mode flag.

Language Services

App.languageServices owns provider registration and serializable document routing for editor-adjacent language features. Providers implement the shared LanguageServiceProvider contract with metadata (id, languages, runtime, priority, and capabilities) plus optional diagnostics, completion, hover, definition, code-action, and dispose hooks. Consumers pass VirtualDocument payloads containing only URI, language id, version, and text, plus serializable positions/ranges and app-contributed global declaration snapshots.

For a given { languageId, capability } pair providers are consulted in descending priority; diagnostics and code-action helpers merge outputs only from providers that share the maximal priority among registered matches so a host-native Electron sidecar (priority > 0) excludes duplicate diagnostics from bundled worker backends without unregistering them. Completions stop at the earliest provider that yields items; hover behaves similarly while definitions bail out once a provider responds with locations.

The API package also exports CodeMirror adapters under @lapis-notes/api/editor/language-service:

• diagnostics through async lint integration via lapisCodeMirrorLint() and enriched mapToLapisLintDiagnostic() output (Svelte lapis-lint-tooltip with markdownlint rule links, copy, View Problem, language-service code actions), plus optional lintGutter()
• completions through @codemirror/autocomplete, with shared defaults and tooltip theming alignment via lapisCodeMirrorAutocomplete() (root export @lapis-notes/api and extensions/autocomplete) composed with @lapis-notes/ui/codemirror-autocomplete.css
• lint tooltip and inline-problem chrome through workspace-loaded CodeMirror CSS (packages/workspace/src/lib/styles/codemirror-lint.css); inner hover layout lives in the Svelte component under extensions/lint/
• vault-driven completion helpers (vaultFilesMatchingPathSubstring, media filters, isImageEmbedLinkPath) for wiki-link sources in first-party plugins
• hover through hoverTooltip
• languageServiceDocumentContext, a Facet for non-file-backed editors such as notebook cell editors that need to resolve a virtual document and map positions/ranges

Adapters only call app.languageServices; markdownlint, TypeScript, future Electron-native providers, and LSP transports stay behind the provider contract.

Supporting Systems

Internationalization

LocalizationManager wraps i18next:

• t(namespace, key, params?) / t(key, params?) — Translate with flexible signature.
• plural(count, ns, key, params?) — Plural forms.
• setLocale(locale) — Switch language.
• addResourceBundle(ns, locale, translations, deep?, overwrite?) — Load translations.
• currentLocale, availableLocales — Reactive state.

Search Utilities

• prepareFuzzySearch(query) → (text) => SearchResult | null — Tries simple match first, falls back to fuzzy.
• prepareSimpleSearch(query) — Substring only.
• SearchResult: { score: number, matches: [start, end][] }.
• renderMatches(el, text, matches) / renderResults(el, text, result) — Highlights match ranges in DOM.
• useTextHighlight(el, { query, value }) — Svelte action that highlights literal query text with text nodes and suggestion-highlight spans without assigning raw HTML.
• sortSearchResults(results) — Sorts by score descending.
• SuggestModal<T>, FuzzySuggestModal<T> — Modal bases for fuzzy search UIs.

History

HistoryManager<T> — Navigation stack:

• pushState(state) / replaceState(state) / updateState(partial).
• back() / forward() / go(steps).
• hasForward / hasBackward — Computed navigation availability.
• maxSize: number — Default 20.

Menu System

Menu with MenuItem children:

• addItem(callback), addSeparator(section?), setTitle(title), setSection(section).
• showAtPosition({x, y, width?, overlap?, left?}), popover(), dropdown().
• setOpen(open), hide(), and close() synchronize renderer menu state and run onHide when an open menu transitions closed.
• search(value) — Filter items.
• MenuItem supports: setTitle, setIcon, setChecked, setDisabled, setWarning, setSection, onClick.
• Shared menu rendering trims separators that would otherwise land at the start or end of the rendered menu after dynamic construction or filtering.
• Shared context, dropdown, and popover renderers use the same drawer-backed presentation on mobile-width viewports while preserving desktop popup behavior.

Popover

HoverPopover (extends Component) with lifecycle states: Hidden → Showing → Shown → Hiding.

DOM Enhancements

enhance.ts patches Node and HTMLElement prototypes:

• Node: detach, empty, insertAfter, appendText, createEl, createDiv, createSpan, createSvg, doc, win.
• Element: find, findAll, getText, setText, addClass, removeClass, toggleClass, hasClass, setAttr, getAttr, matchParent, getCssPropertyValue.
• HTMLElement: show, hide, toggle, toggleVisibility, on (delegated events), off, onClickEvent.

Embed Registry

Maps file extensions to embed view constructors:

class EmbedRegistry {
  embedByExtension: Record<string, EmbedView>;
  register(extension: string, view: EmbedView): () => void;
  get(extension: string): EmbedView | null;
}
type EmbedView = (props: {
  app;
  containerEl;
  state;
}) => void | { destroy?: () => void | Promise<void> };

Bundled and community plugins use this registry to supply plugin-owned inline renderers for markdown file embeds without widening the shared HTML sanitization rules. The markdown package looks up a renderer by file extension for non-image embeds and, when one exists, mounts it into the embed container and runs the returned destroy handle on teardown.

Icon System

• registerIconPacks(loaders: IconLoader[]) — Registers icon sets.
• getSvg(iconName, customisations?) — Returns SVG element. Built-in Lucide icons (24px, 150+).
• Prefixed lookup: lucide:name, custom:name. Prefix optional for Lucide.
• IconLoader: { name, loader? | icons? } — Async or inline icon packs.
• parseCodiconLabel(label) — Splits declarative label text into text, codicon, and registry icon segments for $(token) syntax.
• isLabelIconAvailable(iconName) — Cached async lookup for registry icons used during label rendering fallback.
• Label tokens: unqualified $(play) (codicon font, then registry fallback), qualified $(lucide:file-text) (registry SVG only), optional ~spin modifier. Malformed tokens remain literal text in the rendered label.

Utilities

• apiVersion: "1.12.3" — Current API version.
• cn(...inputs) — Tailwind class merging (clsx + tailwind-merge).
• debounce(cb, timeout?, resetTimer?) — Returns Debouncer with cancel() and run().
• uniqueId(salt?) / md5(string) — MD5-based hashing.
• requireApiVersion(version) — Semver compatibility check.
• stripHeadingForLink(text) — Normalizes heading text for anchor matching.

Tasks and Workers

• Tasks — Promise collection: add(cb), addPromise(p), isEmpty(), promise() waits for all.
• PromiseWorker — Wraps Worker with typed request/response. postMessage<T>(type, data, timeout?) returns a promise (default 10 s timeout). Message format: {id, type, data} → {id, success, result?, error?}.

Markdown Rendering

• MarkdownPostProcessor: (el, ctx) => Promise<void> | void — Sorted by sortOrder (default 0).
• MarkdownPostProcessorContext: { docId, sourcePath, frontmatter, addChild(child), getSectionInfo(el) }.
• MarkdownRenderChild (extends Component) — Lifecycle wrapper for rendered elements.
• MarkdownRenderer.render(app, markdown, el, sourcePath, component) — Static rendering API.
• MarkdownPreviewRenderer — Static registration for post-processors.

Settings UI Components

settings.svelte.ts provides a builder API for settings panels:

Components: TextComponent, ToggleComponent, SliderComponent, SelectComponent, ButtonComponent, ExtraButtonComponent, ProgressBarComponent, DropdownComponent, TextAreaComponent, ColorPickerComponent, IconPickerComponent.

Structure: AppSettings → SettingGroup → Setting → components. Each setting has setName, setDesc, addToggle, addText, addSlider, addSelect, addButton, addColorPicker, etc.

Modals: Modal base with open(), close(), onOpen(), onClose(), containerEl.

SettingTab: Abstract class with display() and containerEl for custom settings panels.

Compatibility Surface

compat.ts provides:

• SecretComponent — Password input field.
• Protocol types: CliHandler, CliFlags, ObsidianProtocolHandler, ObsidianProtocolData.
• moment — Luxon-compatible date library shim for Obsidian API compatibility.

App State and Workspace Model

App — Root State Owner

The App class (packages/api/src/lib/context.svelte.ts) is the root owner for all application state. It constructs and holds every runtime service.

State Ownership Map

Reactivity Model

Files ending in .svelte.ts use Svelte 5 runes for reactive state:

• $state for mutable reactive properties (e.g., WorkspaceTabs.currentTab, Menu.open, CommandManager.open).
• $derived for computed values.
• $effect for side effects on state changes.

This means the workspace model is reactive: UI components automatically re-render when model properties change.

Open-File Flow

When app.openFile(file) runs:

1. Tries to reuse an already-open matching leaf in the focused command host, then falls back to the active main-area leaf.
2. If the active leaf is in a sidebar, falls back to the selected root-split leaf instead of replacing the sidebar view.
3. If no main-area leaf exists, creates a new WorkspaceLeaf in the root split.
4. Determines view type from workspace.editorAssociations, registered editor-view filename patterns, or the registered extension fallback.
5. Looks up the view constructor from the registry.
6. If no registered constructor exists, checks verified official registry contribution summaries for an on-demand install prompt.
7. Creates and mounts the view in the leaf.
8. The leaf’s setViewState() triggers visual update.

When a leaf replaces one TextFileView with another, the previous editor instance is destroyed after the old view unloads. This keeps repeated file switches from accumulating detached CodeMirror editors in memory and turning later navigations into progressively slower reloads.

File navigation is a mutation of the workspace model first, then a visual update. Default file navigation APIs such as app.openFile(file), workspace.openLinkText(...), and workspace.getLeaf(false) target the main root split unless a floating or popout command host currently owns focus. When the focused host already has that file open, app.openFile(file) reselects and reveals the existing leaf instead of reopening the file in another pane. Sidebar APIs such as ensureSideLeaf(), getLeftLeaf(), and getRightLeaf() remain the explicit way to create or reuse sidebar leaves, so clicking a file link from search, tags, backlinks, or another sidebar surface does not replace the sidebar panel even when no main tab is currently selected.

The current implementation also traces this path through app.telemetry. app.openFile(), WorkspaceLeaf.setViewState(), WorkspaceLeaf.openFile(), TextFileView.onLoadFile(), and selected editor reconfiguration steps emit nested spans so slow opens can be attributed to state restore, file I/O, editor state creation, or view mounting. Slow spans capture a lightweight workspace snapshot including active view type, sidebar visibility, leaf counts, enabled plugin count, and a DOM node count bucket.

The browser telemetry service also publishes a small reactive diagnostics snapshot on app.telemetry.diagnostics. It keeps bounded ring buffers for recent slow spans and recent measurements (web-vitals plus longtask) so the diagnostics core plugin can expose a local workspace view without depending on an OTLP backend or browser devtools.

App exposes emulateMobile(enable?) for devtools use: it persists workspace.mobile.mode as always when enable is true or omitted, or as never when enable is false, then reloads the renderer when window is available.

App now also carries a session-scoped safeMode record. It captures temporary startup recovery policy such as disabling community plugins, skipping saved layout restore, or blocking notebook execution for the next reload, plus the last preserved startup failure summary when the user entered Safe Mode from a recovery surface. The workspace shell mirrors this state into context keys so commands and plugins can cheaply gate behavior like notebook execution without consulting renderer-only state.

Workspace.activeLeaf is treated as an in-tree selection, not just a cached pointer. If a close, unload, or layout restore leaves the cached leaf detached from the current split tree, the workspace falls back to the selected leaf from the live tab tree instead of exposing the stale reference to callers. Workspace.activeRootLeaf applies the same validation while only considering the root split, which keeps sidebar-originated default file navigation out of the sidebars without changing focus tracking for sidebar views. When the active leaf belongs to an in-app floating pane or host-backed popout, default file navigation stays in that same floating window so rendered-note link clicks do not jump back to the main root split.

The workspace model also carries a presentation-only displayMode state with values desktop and mobile. This is not a second layout tree and it is not serialized into workspace.json; it exists so the renderer shell and plugins can react to whether the current shell is presenting the shared layout as a desktop or mobile workspace. setDisplayMode() emits a typed display-mode-change event when the mode actually changes, while isMobileMode is the convenience getter used by mobile-aware shell logic. Plugins should treat this as a presentation hint rather than a layout fork: mobile mode can hide visible split chrome, show only one active leaf at a time, and route sidebar-owned leaves through alternative navigation surfaces without changing the underlying workspace tree.

Mobile and adaptive shells use public leaf-control helpers instead of reaching into private tab-selection internals. getOpenLeafEntries() walks the main split, left and right sidebars, and floating or popout windows to expose a flat list of open leaves with region metadata, active state, selected-in-parent state, file path where applicable, and parent tab, group, or window identity. activateLeaf() selects the correct parent tab or sidebar group, unhides a grouped sidebar leaf when needed, and brings floating or popout windows to the front without requiring shell code to understand the workspace tree. The companion closeLeafAndSelectFallback() helper preserves normal close behavior while choosing a sensible remaining leaf when an adaptive shell closes the active leaf.

The workspace also exposes the owning Document for the focused command host. API-owned modal wrappers use that document’s body as their dialog portal target, so popup-triggered dialogs render inside the popup window instead of falling back to the parent renderer document.

The workspace model also exposes getVisibleHintTargets() for bundled keyboard navigation overlays. It scans workspace.containerEl for visible enabled nodes marked with data-hint-target, normalizes the associated data-hint-* metadata into runtime records, and returns only targets whose DOM rects are present in the current shell. This keeps chrome-local opt-in metadata in the workspace renderer while leaving hint-label generation and activation behavior to the owning plugin.

Layout Model

The layout tree is recursive:

WorkspaceSplit (vertical | horizontal)
├── WorkspaceSplit (nested)
│   └── ...
└── WorkspaceTabs
    ├── WorkspaceLeaf (view: MarkdownView)
    ├── WorkspaceLeaf (view: EmptyView)
    └── WorkspaceSidebarGroup
        ├── WorkspaceLeaf (view: SearchView)
        └── WorkspaceLeaf (view: GraphView)

Workspace components in packages/workspace render this tree; they do not own an independent layout model.

Layout Serialization

workspace.getLayout() serializes the full tree to JSON:

• Split types, children, sizes.
• Tab group state (current tab, stacked mode).
• Sidebar group state (id, name, icon, child leaves, hidden child IDs, collapsed child panels, and resized child panel proportions).
• Leaf view states (view type, file path, scroll position, etc.).

workspace.loadLayout(json) reconstructs the tree from JSON. workspace.changeLayout(json) uses the same object-restore path for already loaded layout snapshots, including required view-plugin activation, active leaf restoration, layout-ready notification, and live layout persistence after a successful replacement. Flat sidebar layouts without WorkspaceSidebarGroup entries remain valid, and grouped sidebar layouts round-trip without changing the underlying child leaves. Grouped sidebar panel sizes are optional, so older layouts without panelSizes keep loading with equal panel proportions. requestSaveLayout() debounces persistence to the vault and is queued when restorable workspace state changes, including layout mutations, grouped sidebar panel resizing, sidebar visibility changes, and leaf view or file opens.

Presentation-only workspace state such as displayMode is intentionally kept out of this serialized layout contract, so switching between desktop and mobile shells does not rewrite split sizes, sidebar widths, or other persisted layout state merely because the renderer chose a different presentation.

The workspace model also keeps a transient focusMode record for promoted root tab groups. enterFocusMode(leaf) only accepts leaves that still belong to the root split, exitFocusMode() clears the active promotion without mutating the split tree, and restore paths such as restoreLayoutJson() or focused-leaf teardown clear the transient state before rehydrating layout. Focus mode is intentionally not serialized into .obsidian/workspace.json, so reload always returns to the normal shell layout.

Committed workspace drag/drop mutations now route through shared model helpers instead of direct renderer-side split-tree edits. moveWorkspaceChildToTabIndex() owns top-tab and top-level sidebar reorder, dropWorkspaceItemOnTabs() owns center drops plus edge split drops for leaves and files, and moveLeafToSidebarGroupIndex() / moveLeafToSidebarGroup() own grouped-sidebar panel reorders and group ingestion. Those helpers fire cancelable layout-will-drop events before mutating layout, emit layout-did-drop after success, and finish with a single layout-change marked with source: "drag-drop". When a drop operation needs to clone or open a leaf as part of the mutation, the workspace suppresses transient nested save requests so listeners observe only the final committed drag/drop change.

Command and Keyboard System

Command Registration

Commands are registered with app.commands.registerCommand(cmd):

interface Command {
  id: string; // "plugin:command-id"
  name: string; // "Plugin: Command Name"
  icon?: string;
  repeatable?: boolean;
  callback?: () => any; // Global
  checkCallback?: (checking) => boolean | void;
  editorCallback?: (editor, ctx) => any;
  editorCheckCallback?: (checking, editor, ctx) => boolean | void;
  hotkeys?: Hotkey[]; // Default keybindings
}

Commands with editorCallback are stored separately in editorCommands for editor-context execution.

Keyboard Routing

1. App.svelte captures keydown events at the document level.
2. Records app.lastEvent.
3. Gives any additional overlay scopes first chance to handle the event.
4. When transient workspace focus mode is active, handles bare Escape at the shell boundary before leaf scopes so focused editors cannot swallow the exit action.
5. Forwards remaining events to the active leaf’s Scope.
6. Scope.handleEvent(evt) checks key bindings, calls handlers. Return false to preventDefault.
7. Falls back to command lookup via commandsFor(hotkey) using effective hotkeys from defaults or .obsidian/hotkeys.json overrides.
8. Executes the first available matching command through executeCommand() so when, checkCallback, and editor-scoped command rules still apply.

Keymap

Keymap manages a stack of Scope objects. pushScope(scope) activates, popScope(scope) deactivates. Events process scopes in reverse (LIFO) order.

Scope.register() also supports wildcard capture for modal overlays: key = null matches any non-modifier key at the requested modifier specificity, and modifiers = null matches regardless of modifiers. This is used by the bundled fmode plugin to capture typed hint characters without registering one binding per letter.

Modifier handling:

• "Mod" → Meta on Mac, Ctrl on Windows/Linux.
• "Ctrl" → Ctrl always.
• "Meta" → Meta (Cmd on Mac, Win on others).
• Keymap.isModifier(evt, mod) / Keymap.isModEvent(evt) for platform-aware checks.

Sidebar State

Left and right docks are represented as sidebar state attached to the workspace model. The Workspace exposes leftSplit and rightSplit as WorkspaceSplit instances. The Svelte shell’s Sidebar.Provider and SidebarState consume these to size and render the visible docks.

WorkspaceSidedock wraps each split with show/hide semantics. Visibility is toggled via commands (app:toggle-left-sidebar, app:toggle-right-sidebar).

Those sidebar and leaf counts now also feed the slow-span snapshot path so hot-page regressions can be correlated with current shell state rather than only with the triggering interaction.

When a sidedock leaf is split, the workspace inserts a nested horizontal split inside the existing sidedock branch so the original tab group and the new leaf stay in the sidebar tree instead of replacing each other.

Sidebar views may also be grouped. Workspace.registerSidebarView() stores default placement metadata for a view type, and Workspace.ensureSideLeaf() accepts explicit placement options for side, group identity, group display metadata, and initial hidden state. Groups are model objects, not plugin-owned composite views, so traversal, active-leaf restore, getLeavesOfType(), and layout persistence continue to operate on the real child leaves. The workspace model also exposes helpers to find/create groups and convert sidebar leaves to a group or a group back to normal sidebar tabs.

Hover Preview and Popouts

The workspace keeps hover-link source registrations in-memory so plugins can register them during onload() and rely on component cleanup to remove them on unload.

openPopoutLeaf() and moveLeafToPopout() now request a host-backed popout window instead of reusing the in-app floating overlay path. When the current host registers popout support, the workspace creates a separate Window/Document, mounts the selected WorkspaceWindow tree there, mirrors theme and plugin styles into that document, and removes the popout from layout state when the secondary window closes. When the host does not support popouts, these APIs raise an explicit unsupported error and leave the original leaf attached.

In-app floating panes and host-backed popouts share the WorkspaceWindow model. moveWorkspaceChildToFloating() moves leaves, sidebar tabs, sidebar groups, or grouped sidebar panel leaves into an in-app floating pane, while moveWorkspaceChildToPopout() moves the same item types through the host popout path when supportsPopoutWindows() is true. Floating panes also carry display state: normal, collapsed, minimized, and maximized. Only collapsed and minimized persist in workspace layout JSON; maximized is a transient renderer state that restores as normal after reload. Workspace.getLeaf() returns the active floating or popout leaf for default navigation before falling back to activeRootLeaf, preserving local navigation inside secondary windows while keeping sidebars from becoming the default file target.

The internal moveWorkspaceChildToWindow() helper builds and commits the destination WorkspaceWindow tree to the floating container before detaching the item from its source. This ordering ensures the moved item always has a reachable parent: if the host popout open fails, the item was never detached and remains in the source tree.

Layout Normalization

Before the workspace model is hydrated from persisted JSON, the raw input is passed through normalizeWorkspaceJson(). This pure function repairs common corruption that can accumulate in long-lived .obsidian/workspace.json files:

• Sizes arrays whose length does not match their sibling children array, or that contain non-finite values, are repaired by padding or trimming to match and replacing invalid values with an equal-weight default.
• currentTab indices that are out of range or non-integer are clamped to 0.
• Empty floating windows (no leaf content) are dropped before the model is hydrated.
• Popout-mode windows cannot be restored across sessions and are also dropped.
• Stale sidebar group metadata — hiddenLeafIds, collapsed, and panelSizes entries that refer to leaf ids no longer present in the group’s children — are stripped.
• Unknown or malformed child node types are silently dropped; valid siblings are kept.
• Missing required fields are filled with safe defaults (e.g. generated ids, "16rem" sidedock width, "vertical" split direction).

The normalizer is applied on every call to restoreLayoutJson(), which is the shared entry point for both loadLayout() (file-based restore on boot) and changeLayout() (programmatic restore from an arbitrary object).

Configuration State

See Configuration and Settings for the full schema-driven configuration system.

UI Package (@lapis-notes/ui)

The UI package is the shared design-system layer. It wraps headless component libraries (Bits UI, paneforge, svelte-sonner) in Tailwind-styled Svelte components that the workspace shell and API-level components share.

Source: packages/ui/src/lib/

Design Principles

• Presentation only — no app state, workspace behavior, plugin lifecycle, storage, or metadata.
• Thin wrappers over headless primitives with consistent Tailwind styling.
• Variant-based APIs using tailwind-variants and class-variance-authority.
• Composable: most complex components are exported as namespaced sub-components (e.g., Dialog.Root, Dialog.Content).
• Plugin-specific chrome, selector namespaces, and stylesheet ownership stay in the owning plugin package. Shared UI components should remain generic building blocks instead of accumulating plugin-specific override rules.
• Theme-first styling: shared components consume theme.css semantic variables and prefer hairline borders, 4-8px radii, visible neutral hover states through --background-modifier-hover, selected neutral states through --background-modifier-active-hover, and minimal shadows so workspace and plugin chrome inherit the same Obsidian-aligned surface system.

Theme Tokens

theme.css is the canonical shared palette and Tailwind token bridge entrypoint. Internally it imports grouped partials from src/lib/styles/theme/ for the light palette, dark overrides, semantic aliases, shared foundations, document/content roles, shared surfaces, and Tailwind bridge tokens. Dark mode is the primary target and follows the attached Obsidian default ladder: #1e1e1e background, #242424 card/alternate surface, #262626 secondary/sidebar surfaces, #363636 hairline/sidebar borders, #3f3f3f strong/input borders and sidebar hover surfaces, #dadada text, and #b3b3b3 muted text. Accent roles resolve through --color-accent*; components use semantic --interactive-accent, --text-accent, and --text-on-accent instead of raw --accent-interactive.

Light mode remains supported as a restrained structural mirror. Existing font imports and the mono font stack remain unchanged.

The shared theme continues to expose shadcn/Tailwind variables (--background, --card, --primary, --border, etc.), Obsidian-compatible aliases (--background-primary, --background-modifier-border, --text-normal, --text-muted, --interactive-accent, --text-on-accent), and compatibility helpers (--color-base-*, --color-accent-*, --mono-rgb-*, theme-level selection and shadow tokens, the blur/raised surface chain, and form-field hover helpers) so workspace chrome, first-party plugins, and community-style plugin CSS inherit a single token source.

Theme ownership also includes class-family compatibility: the shared token layer must resolve correctly for both dark/light and theme-dark/theme-light classes when the runtime applies them on either html or body.

The cross-package Style System page is the durable contract for effective tokens, shape language, plugin inheritance, and update rules.

Utilities

• cn(...inputs) — Class merging via clsx + tailwind-merge.
• fuzzySearch(items, query, { keys }) — Shared Fuse.js-backed fuzzy ranking helper for batch filtering when Command.Root uses shouldFilter={false}.
• fuzzyMatchScore(value, query, keywords?) / createFuzzyMatchScore() — Shared per-item Fuse scorer for menus, tags, metadata autocomplete, and other ranked filter lists.
• commandFuzzyFilter / createCommandFuzzyFilter() — Aliases of the per-item scorer for bits-ui Command.Root filter props.
• WithoutChild<T>, WithoutChildren<T>, WithoutChildrenOrChild<T> — Type utilities for removing slot props.
• WithElementRef<T, U> — Adds bindable ref property.

Hooks

IsMobile

IsMobile extends MediaQuery. Constructor takes breakpoint (default 768px). Provides reactive mobile detection.

Component Catalog

Layout Components

Form Controls

Overlay Components

Trigger-backed overlay wrappers now carry a shared popup-document fallback for their portal target. When callers do not pass explicit portalProps, the shared Dropdown Menu, Context Menu, Hover Card, Tooltip, Popover, and Select wrappers portal into the active trigger element’s ownerDocument.body rather than the ambient root document. That keeps popup-hosted overlays attached to the window that raised them without requiring every popup-aware call site to wire its own portal target.

Data Display

Navigation

Feedback

Validation And Exports

The package builds with svelte-package, copies theme.css, styles.css, and codemirror-autocomplete.css into dist, and exposes component subpaths through package exports. Consumers import components directly or through the package index.

During local validation, the package’s Svelte/TypeScript config maps @lapis-notes/ui self-imports and component subpaths back to src/lib so svelte-check runs in a clean checkout without relying on generated dist/ declarations.

Sidebar System

The Sidebar is the most complex component group, designed for the workspace shell’s dock panels:

State Management

• SidebarState class — open, openMobile, state (“expanded”/“collapsed”), isMobile.
• useSidebar() — Context hook for accessing sidebar state.
• toggle(), setOpen(), setOpenMobile(), handleShortcutKeydown().
• Keyboard shortcut: Cmd+B / Ctrl+B.

Constants

• SIDEBAR_WIDTH = "16rem", SIDEBAR_WIDTH_MOBILE = "18rem", SIDEBAR_WIDTH_ICON = "3rem".
• SIDEBAR_COOKIE_NAME = "sidebar:state", SIDEBAR_COOKIE_MAX_AGE = 7 days.

Components

• Provider — Sets up state, CSS variables for widths.
• Root — Conditionally renders as Sheet on mobile.
• Content, Header, Footer, Inset — Layout sections.
• Menu, MenuItem, MenuButton — Menu items with variants (size, variant), tooltip support, icon collapse.
• MenuSub, MenuSubButton, MenuSubItem — Nested menus.
• MenuAction, MenuBadge, MenuSkeleton — Auxiliary menu elements.
• Group, GroupLabel, GroupContent, GroupAction — Section grouping.
• Input, Rail, Trigger, Separator — Utility components.
• Rail shares the same hover/focus-visible accent-line treatment as Resizable.Handle: the visible separator line stays centered, grows from 2px to 4px, and switches to var(--interactive-accent) without changing the drag hit target.
• NestedProvider — For nested sidebar contexts (e.g., right sidebar inside left sidebar).

Dependencies

• bits-ui — Headless Svelte components.
• paneforge — Resizable pane library.
• svelte-sonner — Toast notifications.
• @tanstack/table-core — Data table engine.
• mode-watcher — Dark/light theme detection.
• tailwind-variants / class-variance-authority — Variant styling.
• lucide-svelte — Icons (SearchIcon, X, ChevronDown, Check, Minus used internally).
• @dnd-kit/dom, @dnd-kit/svelte — Table row/column reorder sensors and grip helpers (table-dnd); presentation-only, no vault or document model logic.

Diffmerge Package (@lapis-notes/diffmerge)

@lapis-notes/diffmerge provides Svelte 5 diff and three-way merge UI: DiffMerge2 (two-pane) and DiffMerge3 (three-pane), plus line/block diff helpers, editor chrome, and themed CSS.

Source: packages/diffmerge/src/lib/

Provenance

The implementation is vendored from the mismerge / mergeweave core library (MIT). This monorepo keeps a single package that combines former core sources with the former adapter-svelte packaging model (plain Svelte components, not custom elements). React and Solid adapters are not included.

Exports

The package is built with @sveltejs/package. Consumers should depend on workspace:* and use:

Import the CSS entry that matches the host app’s theme in the same way other packages expose side-effect CSS (see Plugin CSS Contract).

Boundary Rules

• Peer: svelte ^5.0.0.
• Runtime deps: diff, esm-env, nanoid (aligned with other packages using diff 9.x).
• Components are ordinary Svelte exports: hosts mount <DiffMerge2 … /> / <DiffMerge3 … /> like other local components; there is no custom-element bundle in this package.

Integration status

The package is buildable and tested in isolation. No active product surface currently depends on it; the History compare tab uses CodeMirror’s unified merge extension instead.

Package-local summary

For a short index maintained next to the code, see packages/diffmerge/spec.md.

Language Service Package (@lapis-notes/language-service)

@lapis-notes/language-service owns first-party browser language-service providers that are too heavy for @lapis-notes/api or editor plugins. The shared API package owns the contracts and CodeMirror adapters; this package supplies concrete worker-backed providers.

Source: packages/language-service/src/

Providers

• createMarkdownLanguageServiceProvider() starts a markdownlint Web Worker and returns a LanguageServiceProvider for single-document Markdown diagnostics and fix actions. The worker statically imports markdownlint runtime entry points so browser/PWA builds bundle them instead of leaving bare module specifiers for runtime resolution.
• @lapis-notes/language-service/markdown exports the markdown provider factories so the external Markdown Lint plugin can import only markdownlint support without bundling unrelated providers.
• createNativeMarkdownLanguageServiceProvider() creates a bridge-backed Markdown diagnostics provider over the shared desktop_ls_* invoke surface so first-party plugins can own native markdownlint registration without importing Electron host code directly.
• createTypeScriptLanguageServiceProvider() starts a TypeScript Web Worker backed by the TypeScript language-service APIs and @typescript/vfs file-system helpers. It serves TypeScript diagnostics, completions, hover, and definition lookups for virtual documents.

Markdownlint browser and native providers now share a host-neutral runtime helper under src/markdownlint/. That helper owns:

• shared markdownlint options and the custom MD018 replacement alias set
• markdownlint issue -> diagnostic mapping
• markdownlint issue -> code-action generation, including ignore-next-line and ignore-for-file actions
• inline markdownlint suppression alias normalization for MD018
• applyFixes(...)-based edit generation so markdownlint fixes preserve YAML frontmatter and edit the actual violation line instead of rewriting from the top of the file

Providers communicate through the serializable worker protocol exported by @lapis-notes/api. Requests carry virtual document URI, language id, version, text, position/range payloads, and global declaration snapshots. Providers do not receive App, EditorView, DOM nodes, vault files, or plugin instances.

Runtime Boundary

The default runtime ships Web Worker implementations for browser/PWA hosts. Electron desktop still owns the native/process-backed sidecar and desktop_ls_* IPC surface, but first-party plugins now consume the same shared markdownlint runtime helper through bridge-backed provider factories in this package instead of duplicating markdownlint mapping logic in the host shell. The exported worker providers remain authoritative for parity testing in Chromium.

Consumers

• The external official Markdown Lint plugin registers the markdownlint provider for MarkdownViewType consumers when installed and enabled.
• The Notebook plugin registers the TypeScript provider and contributes minimal notebook global declarations for lapis, Inputs, html, svg, Generators, and Promises.
• Workspace TypeScript text views and notebook cell editors consume the shared CodeMirror adapters through app.languageServices.

Notebook Core Package (@lapis-notes/notebook-core)

@lapis-notes/notebook-core is the first extracted package from the notebook runtime refactor. It owns reusable notebook contracts that do not depend on the bundled product plugin, Svelte views, DuckDB-Wasm, workers, or @lapis-notes/api.

Source: packages/notebook/core/src/

Current Scope

The package currently exports:

• the notebook output protocol for text, markdown, HTML, structured input outputs, trusted live DOM, table, chart, image, and error outputs
• notebook cell, document, block, and frontmatter model contracts
• notebook session state, run-state, checkpoint, setup-phase, and progress-event contracts
• table metadata types used by DuckDB-backed query output normalization and dataframe rendering
• runtime feature flags used by worker policy and runtime routing code, including the distinction between broad DOM-related helper usage and live browser DOM requirements
• generic notebook execution result/options contracts, including a typed runtime dependency loader hook, a host-neutral notebook file reader provider contract, and a JavaScript-like compile provider contract for TypeScript/ESM rewriting hosts
• generic notebook graph types and pure graph helpers for graph construction from analyzed cells, dependency closure, stale descendant collection, duplicate-definition detection, topological order, and cycle detection
• pure language-service projection helpers that concatenate TypeScript cells into a virtual TypeScript document and map provider positions/ranges back to cell-local coordinates
• subpath exports for @lapis-notes/notebook-core/execution, @lapis-notes/notebook-core/graph, @lapis-notes/notebook-core/language-service, @lapis-notes/notebook-core/model, @lapis-notes/notebook-core/outputs, @lapis-notes/notebook-core/runtime-features, and @lapis-notes/notebook-core/session

The bundled notebook product plugin still owns notebook parsing, frontmatter normalization, analyzer selection, UI, the concrete NotebookSession runtime, persistence, worker selection, DuckDB runtime setup, and command wiring. It consumes and re-exports the core model/output/session protocol through compatibility shims and binds core graph construction to the current TypeScript, SQL, and markdown analyzers through a product-plugin wrapper.

Notebook execution provider contracts live here when they are host-neutral. The file reader provider receives notebook paths plus the source note path so browser, worker, and future desktop hosts can preserve notebook-relative syntax while swapping the underlying file-read implementation. The JavaScript-like compile provider receives the original JavaScript or TypeScript cell source plus source/cell metadata and returns executable source with any static notebook import rewrites already applied. Browser execution continues to use the product plugin’s default vault reader and lazy TypeScript compiler when no providers are injected.

Boundary Rules

Notebook core must stay host-neutral and startup-cheap.

• Do not import Svelte, @lapis-notes/api, DuckDB-Wasm, htl, Observable inputs, d3, Plot, or worker entry points from this package.
• Keep exports focused on stable contracts and pure helper functions that are not notebook-authored builtin implementations.
• Move additional runtime contracts here only when they can be extracted without carrying product-plugin lifecycle or host dependencies with them.

Follow-Up Direction

Additional host-neutral contracts can move here later if they emerge from the notebook product runtime, but the current package-split plan does not require another core extraction before the product plugin can continue owning concrete runtime behavior.

The current output protocol now reserves a first-class input output kind for reconstructable notebook controls. That contract is host-neutral: it describes the persisted control artifact, including the owning cell id, exported variable name, input type, current scalar value, optional serializable config, reconstructable flag, and optional source metadata. Live DOM nodes remain out of scope for notebook core and continue to be represented separately as ephemeral dom outputs.

Notebook DuckDB Package

Status: Implemented for the current package boundary. packages/notebook/duckdb owns shared DuckDB runtime contracts, app-table and vault-file registration contracts, catalog/preview types, and pure query/catalog helpers consumed by the notebook product plugin.

Purpose

@lapis-notes/notebook-duckdb separates reusable DuckDB-facing notebook contracts from the product plugin. The package owns runtime TypeScript interfaces, query row/result types, app-table and vault-file registration contracts, catalog/preview types, DuckDB type mapping, normalization into notebook table metadata, and small SQL/catalog helpers.

Current Scope

• NotebookDuckDbRuntime and NotebookDuckDbRuntimeProvider contracts
• NotebookDuckDbColumnDefinition table registration contract
• DuckDbQueryRow and DuckDbQueryResult types
• row normalization for scalar/object DuckDB results
• query result normalization into notebook table columns, column metadata, row counts, query timing, and source SQL metadata
• DuckDB type-name mapping for notebook table column categories
• catalog and table-preview types for inspector/runtime surfaces
• information-schema table-type normalization
• DuckDB identifier quoting for generated service queries
• createNotebookDuckDbCatalog(options) for building notebook catalog models from information-schema table/column rows and a host-provided row-count callback
• pure catalog/preview SQL helpers, preview-limit normalization, row-count normalization, and createNotebookDuckDbTablePreview(options) for shaping table preview rows
• NotebookAppTablesSnapshot, NotebookAppTableRegistrar, NOTEBOOK_APP_TABLE_COLUMNS, and registerNotebookAppTablesSnapshot(service, snapshot) for registering app-derived tables into any runtime-shaped registrar that can create JSON tables
• resolveNotebookVaultPath(path, sourcePath?), NotebookVaultFileReader, NotebookVaultFileRegistrar, and registerNotebookVaultFile(service, reader, alias, path, sourcePath?) for resolving notebook-relative vault file references with the shared stdlib path-normalization rules and either registering host-read file buffers or handing the resolved path to a native runtime registrar
• createDuckDbSchemaSql(schema) and createDuckDbJsonTableSql(options) for creating stable DuckDB SQL used by product runtimes when registering JSON-backed notebook tables

Boundary Rules

This package must stay independent of product-plugin runtime code. It must not import @lapis-notes/api, Svelte, worker entrypoints, vault adapters, app-table snapshot collectors, DuckDB-Wasm, or DuckDB asset URL imports. Browser/PWA asset URL resolution belongs to @lapis-notes/notebook-duckdb-assets; the product plugin owns app-table snapshot collection, actual vault file reads, native vault-path registration, concrete query execution, and the concrete DuckDB-Wasm service lifecycle. Sharing notebook-relative path normalization with @lapis-notes/notebook-stdlib is allowed so DuckDB registration and notebook file helpers keep one path contract.

Consumers

@lapis-notes/notebook consumes this package from the concrete DuckDB service, app-table registration adapter, vault-file adapter, inspector data surfaces, and notebook execution paths.

Notebook DuckDB Assets Package

Status: Implemented for the current package boundary. packages/notebook/duckdb-assets owns the current browser/PWA DuckDB-Wasm and DuckDB worker asset URL resolver consumed by the notebook product plugin.

Purpose

@lapis-notes/notebook-duckdb-assets separates DuckDB asset ownership from the product plugin’s DuckDB service. The product plugin still owns DuckDB lifecycle, table registration, query execution, catalog inspection, and notebook progress phases, but raw wasm and worker URL imports live behind this resolver package.

Current Scope

• MVP DuckDB-Wasm module URL
• exception-handling DuckDB-Wasm module URL
• MVP DuckDB browser worker URL
• exception-handling DuckDB browser worker URL
• getNotebookDuckDbBundles() resolver compatible with duckdb.selectBundle()

Production builds copy DuckDB wasm and worker files to dist/duckdb/ instead of inlining them into JavaScript bundles. Official notebook releases include those paths in the signed .lapis-plugin bundle, so first SQL execution resolves installed plugin asset URLs without making a post-install release download.

Boundary Rules

This package must stay asset-only. It should not instantiate DuckDB, open connections, register files, query tables, import app APIs, or depend on product-plugin runtime code. Browser/PWA asset resolution can evolve here without changing notebook query behavior.

Consumers

@lapis-notes/notebook consumes this package from NotebookDuckDbService when that service is lazily loaded by DuckDB-backed notebook execution or inspection paths.

Notebook Input Package

Status: Implemented for the current host-neutral boundary. The package owns the Observable-style viewof source transform, tracked input metadata, DOM input node binding helpers, callback-driven view runtime helpers, and the current local Inputs runtime built from @lapis-notes/ui primitives for the supported control set. Remaining parity work is tracked by task id TASK-NOTEBOOK-001.

Purpose

@lapis-notes/notebook-input separates notebook input source helpers and tracked DOM/input lifecycle behavior from the product plugin. The current extraction owns the constrained Observable-style viewof transform, tracked input metadata, DOM input node value/listener helpers, the callback-driven lapis.view binding workflow, and the local runtime surface whose supported controls render through shared @lapis-notes/ui primitives. The product plugin continues to own input DOM registration, notebook session writes, output id allocation, and rerun scheduling.

Current Scope

• transformObservableViewof(source) rewrites supported top-level viewof name = expression declarations into const name = await lapis.view(name, expression) calls.
• findObservableViewofDefinitions(source) returns unique viewof names for source-level analysis.
• The transform uses the canonical lapis global name from @lapis-notes/notebook-stdlib.
• loadNotebookDomRuntime() lazily assembles the DOM-backed notebook runtime surface for hosts that have already chosen in-process DOM execution. That runtime owns the Inputs namespace exposed to notebook cells, pairs it with html and svg helpers from notebook-stdlib, routes supported controls through @lapis-notes/ui primitives for app-level UI parity, and throws explicit errors for unsupported factories.
• createTrackedNotebookInputs(inputs) wraps Observable input factories so reconstructable controls can attach host-neutral metadata to the returned DOM nodes without parsing source text.
• styles.css gives notebook hosts a notebook-input-owned stylesheet entrypoint for the current UI-backed controls without importing upstream styles directly from the product plugin.
• attachNotebookInputMetadata(value, metadata) and getNotebookInputMetadata(value) expose the private metadata attachment surface used to carry input type, current value, serializable config, reconstructable flag, and source details from tracked Observable inputs into a runtime host.
• canReconstructNotebookInput(metadata) and reconstructNotebookInputNode(metadata) let runtime hosts decide whether persisted structured inputs are directly rebuildable and recreate supported controls from stored metadata without re-running the owning cell. Newly created metadata identifies the local runtime with source.library: "@lapis-notes/notebook-input".
• isTemplateStringsArray(value) and exported htl template tag types support runtime hosts that bridge lapis.html/lapis.svg with htl tagged template calls.
• bindNotebookInputNode(node, options) seeds an optional initial DOM input value, reports the current value, binds input and change listeners, and returns a disposer for the runtime host to attach to its DOM-output lifecycle.
• getNotebookInputNodeValue(node) and setNotebookInputNodeValue(node, value) provide shared DOM input value access for hosts without owning persistence policy.
• createNotebookViewRuntime(options) builds the async lapis.view(name, input) host function from callbacks. It resolves promised DOM nodes, validates that the result is a DOM node, reads any tracked input metadata, binds input listeners, writes the current value through host callbacks, registers the live DOM output, appends the host’s typed output, and emits input-change events through the host callback.
• isNotebookDomNode(value) provides shared DOM-node detection for runtime hosts that need to classify cell return values.

Boundary Rules

This package must stay host-neutral at import time. It may lazily load DOM-only helper code, the Svelte runtime, and @lapis-notes/ui primitives only inside loadNotebookDomRuntime(), so workspace boot and non-DOM notebook runs stay startup-thin. It must not import @lapis-notes/api, product-plugin modules, notebook session managers, workers, or DuckDB at top level. Runtime hosts are responsible for deciding when DOM-backed execution is available, passing host callbacks into createNotebookViewRuntime, registering live DOM outputs, persisting scalar input values, turning tracked input metadata into product-level structured outputs, and emitting rerun requests.

Consumers

@lapis-notes/notebook consumes this package from notebook analysis, render DOM detection, and cell execution paths. The DOM helper surface still loads lazily only for DOM-backed notebooks, while notebook-input adds the tracked wrapper and the UI-backed control factories that let notebook inputs hand reconstructable metadata to the product runtime and rebuild supported controls from persisted structured outputs without changing the package’s host-neutral boundary.

Notebook Stdlib Package

Status: Implemented for the current package boundary. packages/notebook/stdlib owns current notebook builtin registry contracts, documented bare global names, the pure user-executed lapis output helper implementations, user dependency descriptor/registry validation contracts, the shared runtime dependency loader helpers, source-level runtime feature detection for standard-library-backed helpers, the host-neutral vault/file helper implementations used by notebook runtime hosts, the raw DOM helper loader for html/svg, the host-neutral DOM, Promises, and Generators helper implementations, and the host-neutral bootstrap used to assemble bundled stdlib bindings for notebook execution.

Purpose

@lapis-notes/notebook-stdlib is the shared contract and helper-implementation package for Lapis notebook builtins and user dependency registry metadata. It gives the product plugin and future dependency-management UI one source of truth for which names are Lapis-owned, which bare globals are documented conveniences, how dependency globals are derived and validated, how configured dependencies resolve into runtime globals, which source references require broad DOM-aware handling versus live browser DOM execution or DuckDB-backed execution, how vault-backed file helpers normalize notebook-relative paths, how DSV attachment loaders preserve table columns, and how bundled stdlib helpers are assembled for notebook execution.

The package is intentionally host-neutral. It does not load htl, DuckDB-Wasm, worker code, Svelte UI, or app APIs at workspace boot. Host-specific runtime wiring still lives in the product plugin, but shared host-neutral helper implementations such as vault-backed file attachment plumbing and dynamic bundled-helper bootstrap can live here so notebook-callable helper behavior stays centralized without making workspace boot expensive.

Current Scope

• canonical lapis global name
• pure lapis output helper implementations for typed text, markdown, HTML, DOM, input, table, chart, image, and error outputs
• current lapis.* builtin member names, including output helpers, duckdb, vault, FileAttachment, md, tex, d3, Plot, DOM, Generators, Promises, view, Inputs, html, and svg
• documented bare convenience globals: Inputs, html, svg, md, tex, d3, Plot, DOM, Generators, and Promises
• validation for future user dependency globals, including identifier syntax, reserved builtin names, and duplicate configured names
• host-neutral user dependency descriptors with pinned package versions, optional explicit globals, resolver metadata, package-name-derived default globals, whole-registry validation, and shared runtime dependency resolution helpers for referenced globals
• source-level detection for broad DOM helper references, live browser DOM runtime references, DuckDB runtime references, and bundled visualization helper references
• host-neutral notebook file helpers including notebook-relative path normalization, vault runtime adapters backed by host file readers, and FileAttachment helpers for arrayBuffer, text, json, blob, csv, and tsv
• host-neutral raw DOM helper loading for htl, exposed for notebook-input so the input runtime can pair bare html and svg helpers with its own Inputs namespace ownership
• host-neutral DOM helper implementations for canvas, context2d, download, and uid, patterned after the Observable stdlib namespace and exposed under both lapis.DOM and the documented bare DOM global
• host-neutral Promises and Generators helper implementations patterned after Observable stdlib namespaces and exposed under both lapis.* and documented bare globals
• host-neutral runtime bootstrap for bundled stdlib helpers, currently including lapis.md, lapis.tex, lapis.d3, lapis.Plot, lapis.DOM, lapis.Generators, lapis.Promises, and their documented bare globals during JavaScript-like execution

Consumers

@lapis-notes/notebook consumes this package for pure lapis output helpers, runtime feature detection, inspector DuckDB detection, notebook dependency-analysis reserved globals, shared runtime dependency loading helpers, the raw html/svg DOM helper loader used under notebook-input, the shared DOM, Promises, and Generators namespaces, the stdlib bootstrap for bundled helpers, and vault-backed lapis.vault/lapis.FileAttachment helper implementations. @lapis-notes/notebook-duckdb also reuses the shared notebook-relative file-path normalization so DuckDB vault-file registration and notebook file helpers obey the same path rules.

Boundary Rules

Host-specific implementations should remain lazy and must not make workspace boot load DOM, DuckDB, visualization, or remote dependency resolver code. DOM control wiring, DuckDB service execution, and remote dependency loading still belong outside this package; host-neutral file helper implementations and bundled-helper bootstrap are allowed here because they depend only on host-provided file readers or package-local dynamic imports.

Notebook Worker Package

Status: Implemented for the current package boundary. packages/notebook/worker owns generic notebook worker transport contracts and host request promise plumbing consumed by the notebook product plugin.

Purpose

@lapis-notes/notebook-worker separates worker transport message contracts, host-neutral worker-side request plumbing, main-thread command promise plumbing, main-thread host response wrapping, worker-side shell dispatch, and pure worker eligibility policy from the product plugin. The package owns protocol shapes, request id/promise settlement for both main-thread commands and worker-to-host calls, generic host response envelopes and transfer-list selection, generic worker-side command/response dispatch, and the reusable decision for whether a runtime feature set may use a worker; concrete worker startup, worker URL imports, request semantics, response application, host adapters, feature analysis, fallback execution, and execution remain in @lapis-notes/notebook.

Current Scope

• stable notebook worker channel names
• generic execute command request and response messages
• generic progress messages
• host request and host response messages
• generic incoming/outgoing worker message unions
• NotebookWorkerCommandBroker for creating command ids, creating command messages, tracking pending command promises, looking up command context for progress events, and rejecting outstanding commands when a worker stops
• NotebookWorkerShell for dispatching incoming worker messages, settling host responses, wrapping execute command results/errors as command responses, and posting progress messages with the active command id
• NotebookWorkerHostRequestBroker for posting host requests, tracking pending request promises, settling host responses, and rejecting outstanding requests when a worker shell tears down
• NotebookWorkerHostRequestResponder for resolving main-thread host requests through product-provided callbacks, wrapping success/error host responses, and selecting transfer lists for transferable response values
• shouldUseNotebookWorkerRuntime(input) for deciding whether a runtime feature set can use a worker, based on worker availability, DuckDB usage, live browser DOM requirements, injected dependency loaders, host-only providers, and unsupported dependency resolver kinds
• hasUnsupportedNotebookWorkerRuntimeDependency(dependencies) for checking whether dependency descriptors require main-thread execution because they are not remote ESM descriptors

Boundary Rules

This package must stay host-neutral. It must not import @lapis-notes/api, Svelte, notebook product-plugin models, worker entrypoints, DuckDB, TypeScript, DOM runtime packages, or app host adapters. Product runtimes bind protocol generics to their document/result/progress types, decide what each command and host request means, provide the execute implementation used by NotebookWorkerShell, provide host request resolver callbacks used by NotebookWorkerHostRequestResponder, apply command responses to local state, and supply runtime feature facts to the worker policy helper.

Consumers

@lapis-notes/notebook consumes this package through a product-plugin alias layer that binds the generic protocol contracts to current notebook document, execution result, persisted cell-state, and progress-event types. Its concrete worker entrypoint uses NotebookWorkerShell plus NotebookWorkerHostRequestBroker for app-table and vault-file host calls, and its worker client uses NotebookWorkerCommandBroker, NotebookWorkerHostRequestResponder, and the shared policy helper after product-plugin feature analysis.

Web Host (@lapis-notes/web)

The web package is the deployable browser/PWA host. It wraps the shared workspace renderer with host-level concerns that should not live inside @lapis-notes/workspace: the HTML document shell, PWA manifest and icon generation, service-worker registration, install affordances, and cross-origin-isolation headers needed by the browser-local SQLite runtime.

Source: packages/web/src/

Responsibilities

• Mounts the shared workspace renderer by importing mountWorkspaceApp() from @lapis-notes/workspace/components/app.
• Shows browser-only host status items in the shared workspace status bar, including the shared app version item, a dismissible install affordance when the browser exposes beforeinstallprompt, a pending-update affordance that can reopen the host update prompt, and an icon-only offline indicator when the browser network state drops offline.
• Owns the browser host document (index.html), including title, light/dark bootstrap theme-color metadata, installable icon links, and the early telemetry seed object.
• Generates the browser-host icon set from the shared workspace logo.svg, keeping the favicon plus Apple touch and PWA PNG assets in sync.
• Supports repo-root Nixpacks builds through nixpacks.toml, which runs pnpm --filter @lapis-notes/web build so deploy-time builds keep the full pnpm workspace available.
• Provides a Docker Hub image path for static Web/PWA hosting as lapisnotes/web, built from the same repo-root package build and served by a nonroot distroless Caddy runtime on port 8080 with /healthz for deployment health probes. The published image version follows the web package CalVer from packages/web/package.json.
• Mirrors the browser-host headers required for SharedArrayBuffer-backed SQLite (Cross-Origin-Embedder-Policy: require-corp, Cross-Origin-Opener-Policy: same-origin).
• Configures vite-plugin-pwa to emit the web app manifest plus a generated service worker for offline startup.
• Registers a web-app protocol handler for web+lapis:// where the browser supports installed-PWA protocol handling, routing launches through /open?url=... before the shared renderer dispatches the embedded app URL.
• Provides the Web/PWA plugin asset server for verified installed plugin files, mirroring supported JavaScript, CSS, JSON, WASM, and image assets into Cache Storage under version/hash /__lapis/plugins/[vault-id]/[plugin-id]/[version]/[sha256]/[path] URLs.
• Provides a dismissible host-level install affordance in the shared status bar when beforeinstallprompt fires and hides it after installation, explicit dismissal, or prompt consumption.
• Surfaces pending service-worker updates through a host-owned bottom-right prompt with Later and Install Now actions instead of auto-reloading as soon as the browser detects a waiting worker.

Boot Surface

Entry Point (main.ts)

Reads the shared bootstrap appearance mode from IndexedDB-backed vault state, applies light/dark/system classes to the document root, initializes web-host document metadata, registers Window Controls Overlay handling, starts host theme-color synchronization, mounts the shared workspace app into #app, then calls registerWebPwa().

Web Host Document (pwa-host-document.ts)

• Marks the host document with data-pwa-host="true" and data-runtime="web-pwa" before the workspace renderer mounts so PWA title-bar CSS can apply immediately.
• Detects installed-PWA display modes and sets platform metadata (data-os, data-engine) used by the shared shell layout.

Host Theme Color (host-theme-color.ts)

• Resolves the shared --workspace-chrome-background shell token from the same CSS variable chain used by sidebar and top-tab headers.
• Replaces bootstrap light/dark theme-color metas with one dynamic meta tag once the host can read computed theme values.
• Re-syncs when the document root appearance classes change or when prefers-color-scheme changes.

Window Controls Overlay (pwa-window-controls.ts)

• Tracks installed-PWA display mode (standalone or window-controls-overlay) on the document root.
• When the browser activates window-controls-overlay, sets data-pwa-titlebar-hidden="true" and mirrors navigator.windowControlsOverlay geometry into CSS custom properties so the shared workspace tab header can replace the native title bar on Chromium desktop PWAs. The web host document initializes data-pwa-titlebar-hidden="false" on boot and pwa-window-controls.ts keeps the attribute explicit ("true" in WCO, "false" in standalone) for every data-pwa-host="true" document. PWA chrome header borders and the optional :root::before divider paint only when data-pwa-titlebar-hidden="false".
• Derives platform-specific safe-area insets from the overlay rectangle: macOS reserves leading space for traffic lights, Windows and Linux reserve trailing space for caption buttons, and all platforms reserve top space for the hidden title bar height. Collapsed title-bar geometry reports height 0 and clears the top inset so tabs stay visible instead of being negative-margin clipped.
• The shared workspace shell CSS consumes those properties under html[data-pwa-host="true"] to draw the tab header edge-to-edge while keeping macOS traffic-light clearance. Top tabs and both sidebar dock tab rows remain visibly painted in collapsed and expanded Window Controls Overlay geometry because the sidebar tab buttons use explicit nav-item foreground colors instead of inherited text color; macOS left-dock clearance is split-scoped after subtracting the ribbon width, Windows/Linux right-dock clearance applies to the right sidebar tab row, and WCO chrome rows keep the shared sidebar header bottom border.
• Existing installs must be removed and reinstalled after manifest changes for Window Controls Overlay to take effect; standalone fallback keeps the native title bar.

PWA Registration (pwa.ts)

• Uses virtual:pwa-register so the generated service worker can report waiting updates without auto-applying them.
• Skips service-worker registration during local development and clears stale dev registrations/caches so the shared workspace shell starts without PWA-induced reload races.
• Marks the document as offline-ready when the service worker finishes preparing caches.
• Tracks browser network state separately from offline-ready shell caching, mirroring the current network mode onto the document root and the shared status bar.
• Waits for the mounted workspace app’s command registry and status bar services before registering browser-only install commands or status items, because globalThis.app can exist before all runtime services are initialized.
• Registers browser-only status-bar items for Install and Dismiss when the browser exposes the deferred install prompt event.
• Registers browser-only status-bar items for Update and offline network state, and mounts a host-owned prompt component above the shared status bar so update UI stays in the web host boundary instead of the notifications plugin.
• Persists explicit dismissals in browser storage so the custom install affordance stays hidden across reloads while leaving browser-native install entry points available.
• Hides the install affordance after installation completes or after the deferred prompt is consumed.
• Polls for new service-worker versions when the PWA returns to the foreground or regains connectivity, then exposes Later semantics by hiding the prompt while keeping the waiting update available through the status bar until the user installs it or reloads.
• Leaves native lapis:// handling to desktop shells. Browser/PWA launches use the web-supported web+lapis:// protocol handler and the /open?url=... route because browsers do not generally allow arbitrary bare custom schemes for installed web apps.
• Installs a host-owned PluginAssetServer into the shared workspace mount. The server reads verified installed-plugin metadata from .obsidian/installed-plugins.json, checks installed file paths, sizes, and SHA-256 hashes through the shared API helper, writes supported assets into the lapis-plugin-assets-v1 Cache Storage bucket, and returns same-origin /__lapis/plugins/<vault-id>/<plugin-id>/<version>/<sha256>/<path> module URLs for future renderer ESM plugin imports.

Vite Host Config (vite.config.ts)

• Reuses the same dev-time source aliases as the workspace dev shell for bundled first-party plugins, including explicit first-party UI subpaths such as @lapis-notes/ui/table-dnd/sensors and @lapis-notes/ui/table-dnd/utils that do not map through the wildcard component export shape.
• Installs the shared plugin-host import-map Vite plugin so web/PWA HTML receives the generated app-owned host import map before renderer modules load.
• Resolves $lib against the owning first-party source package during local development so workspace renderer modules and directly sourced bundled plugins can keep package-local imports.
• Enables vite-plugin-pwa in generateSW mode with a manifest that prefers window-controls-overlay, falls back to standalone, and uses shell-aligned theme_color / background_color values instead of static brand blue.
• Leaves Workbox in prompt-mode update flow by avoiding eager skipWaiting, so a newly downloaded service worker stays waiting until the host update prompt asks the user to install it.
• Disables vite-plugin-pwa’s dev service worker so local web-host startup matches the workspace dev shell and avoids stale cached layout state during HMR.
• Raises workbox.maximumFileSizeToCacheInBytes to 50 MiB so large browser-only runtime assets remain eligible for precache.
• Adds a Workbox CacheOnly runtime route for /__lapis/plugins/ that serves only plugin assets already mirrored into Cache Storage by the active workspace runtime. This keeps dynamic module loading same-origin while avoiding a broad vault-file service worker route.

Build Context

The web host is built from the repository root when a deployment system performs a fresh install, because the package resolves workspace dependencies and source aliases against sibling packages across the pnpm monorepo. The repo-root nixpacks.toml captures that supported path by overriding the default Node build command to pnpm --filter @lapis-notes/web build while leaving the existing package-local build script authoritative for icon generation and the Vite bundle.

The repo also provides docker/web/Dockerfile for publishing the Web/PWA host as lapisnotes/web. The Docker build installs the @lapis-notes/web workspace dependency closure from the repository root, passes LAPIS_BUILD_COMMIT through to the Vite build so the shared About dialog can expose the source commit, labels the image with OCI title/description/source/revision/version/license metadata, and copies packages/web/dist into a Docker Hardened Images Caddy runtime (dhi.io/caddy:2). The runtime listens on port 8080, returns 200 ok from /healthz, disables Caddy admin/config persistence and automatic HTTPS, expects TLS termination at the ingress layer, serves hashed Vite assets with immutable caching, serves HTML/service-worker/manifest files with no-cache semantics, preserves 404 responses for missing file-like asset requests, and falls back to index.html for app routes such as /open?url=....

Icon Generation (scripts/generate-pwa-icons.mjs)

• Copies the shared workspace logo.svg into public/favicon.svg.
• Rasterizes the shared lapis.png app tile into padded PNGs for install surfaces: apple-touch-icon.png (180x180) and pwa-192x192.png / pwa-512x512.png / pwa-1024x1024.png center the logo at 82% scale (~9% inset per side), and dedicated pwa-*-maskable.png outputs center the logo at 80% scale for the maskable safe zone.

Offline Scope

The current web host precaches the built application shell and browser-local runtime assets, including large WASM and worker bundles that power SQLite, DuckDB, PDF rendering, and notebook execution. After a successful online load, the browser host can reopen the core app shell offline and continue working with browser-local vault and generated-state storage.

That offline guarantee currently applies to the shipped host shell and browser-local features. Optional features that intentionally fetch remote resources on first use, such as notebook dependency URLs resolved through esm.sh or transformer model assets pulled from Hugging Face, remain outside the precached shell and degrade when the network is unavailable.

lapis.md Site (@lapis-notes/lapis.md)

The lapis.md package is the deployable public documentation and marketing site for Lapis Notes. It serves the landing page, end-user help, and plugin developer docs as static HTML at https://lapis.md.

Source: packages/lapis.md/

Responsibilities

• Builds a static Astro + Starlight site with dual doc trees at /help/ and /developers/.
• Generates a TypeScript API reference under /developers/api-reference/ from the curated packages/api/src/lib/docs-api.ts entry point before Astro dev/build/check, preserving source-driven descriptions and Forgejo Defined in links for the published plugin API.
• Provides a custom marketing landing page at / with CTAs to the app, help, and developer sections.
• Publishes top-level legal pages at /privacy/, /terms/, and /license/, linked from the shared site header/footer and the Starlight docs header.
• Uses a shared Obsidian-style multi-column site footer pinned to the page bottom on the landing and legal shells only; Help and Developer docs pages with sidebars omit it.
• Top header nav links highlight the active section with a dark surface pill and matching ink text.
• Narrows the desktop docs On this page rail to 18.75rem (~300px) with a custom PageSidebar.astro override so Starlight’s default viewport-percent TOC width does not expand the rail on wide screens.
• Renders a starlight-site-graph interactive graph above the desktop docs On this page rail for /help/ and /developers/ pages, using the package’s sitemap generation while preserving the site-local PageSidebar.astro override. Generated /developers/api-reference/ pages are excluded from graph data and hide the graph panel because they are not graph nodes, keeping the Developer docs graph focused on authored guide pages.
• Treats /help/ and /developers/ as first-class docs home pages inside the normal three-column docs shell instead of Starlight splash pages, so the left nav, center article, and right TOC appear immediately on load.
• On wide Help and Developer docs pages, spare horizontal space is split into outer margins on both sides through --lapis-page-gutter, a custom TwoColumnContent.astro override, and matching shifts in PageFrame/header padding so the left nav, article, and TOC sit in a centered three-column shell instead of hugging the viewport edges. The /help/ and /developers/ home pages keep the same centered shell and additionally drop the usual header bottom border.
• Applies an Obsidian-aligned public-site light/dark token map in src/styles/lapis-starlight.css, matching the app’s canvas, violet accent, hairline border, and compact radius language without importing app runtime CSS.
• Uses the Lapis logo SVG as the site favicon at /favicon.svg.
• Exposes root orchestration scripts: dev:site, build:site, and preview:site.
• Produces a dist/ artifact for static hosting; DNS target for docs is separate from app.lapis.md.

Technology

Boot / Dev Surface

Local dev

pnpm dev:site

Build

pnpm build:site

The site package is self-contained for public-site styling and does not need the UI package to prebuild before Astro bundles styles.

Content Model

• Landing — src/pages/index.astro with shared SiteLayout.astro header/footer and generated product-evidence captures for editing, markdown/graph/canvas views, bases, plugins, notebooks, tasks, slides, search, and PDF. The lower markdown/graph/canvas and bases/plugins/notebook sections stack three full-width landing-band rows with large landing-shot--feature frames rather than a multi-column card grid.

• Legal pages — src/pages/privacy.astro, src/pages/terms.astro, and src/pages/license.astro use SiteLayout.astro and the site-local legal prose styles. They publish current-state policy text for local-first privacy, terms of use, package licensing, third-party notices, and trademark boundaries. Legal links appear in the landing/legal header and footer, and StarlightHeader.astro adds the same links to the desktop docs header.

• User help — src/content/docs/help/** (getting started, VS Code-inspired UI layout/shortcut guidance, notes, a comprehensive editing reference, screenshot-backed plugin pages including a multi-page Notebook subsection, desktop/web, import, support, and attributions). The /help/ landing page is a normal docs article inside the shared sidebars-and-TOC shell rather than a standalone splash page.

• Developer docs — src/content/docs/developers/** (plugin model, runtime overview, manifest, lifecycle, development workflow, App/vault/workspace/editor/events/metadata/notices/settings API surface, language and editor extensions, CSS contract, publishing, trust, and safe mode). The /developers/ landing page follows the same docs-shell treatment so plugin authors land directly in the main documentation layout.

  /developers/api-reference/ is generated from TypeDoc markdown through a site-local wrapper script that injects Starlight frontmatter, rewrites TypeDoc’s class pages from classes/ to class-docs/ for Astro route compatibility, and preserves repo source links back to Forgejo. The generated pages stay checked into the repo as normal site content and are refreshed explicitly with pnpm --filter @lapis-notes/lapis.md api-docs:generate. TypeDoc reads packages/lapis.md/typedoc.tsconfig.json, which extends the API dev tsconfig so first-party imports resolve from source and API reference generation does not depend on prebuilt dist/ artifacts.

  The Language & editor extensions section under /developers/language-extensions/ documents the public plugin surface for VS Code-inspired editing: CodeMirror/Lezer syntax registration, editor views and associations, LanguageServiceProvider, lapis.contributes manifest metadata, and CodeMirror extension registration. It maps those concepts from the VS Code language-extension model without documenting TextMate grammars, LSP wire protocol, or internal boot details.

The public site supports light, dark, and Default themes through Starlight’s theme toggle on docs pages and a matching control on the landing/legal header. Default is the initial selection on page load: the main site uses dark, while /help/ and /developers/ docs use light. Explicit light or dark choices persist in localStorage under starlight-theme across docs, landing, and legal shells via shared data-theme tokens in src/styles/lapis-starlight.css.

Public documentation content may adapt permissively licensed upstream documentation when attribution and license requirements are preserved on the site. Current attribution lives under Help and Support.

Public developer pages describe the supported plugin API only. Internal boot/runtime detail stays in spec/.

The public help docs may show syntax examples directly when Starlight can render them faithfully, but vault-aware markdown features that depend on the app renderer should be documented with syntax plus real captured app evidence rather than approximated by the site markdown pipeline.

Visual System

The public site uses an Obsidian-aligned software-documentation style with light and dark palettes:

• Dark: canvas #171717, card surface #1e1e1e, hairline #262626, ink #e5e5e5, muted ink #b3b3b3, accent #a78bfa, and filled action violet #8a5cf5.
• Light: canvas #ffffff, card surface #fafafa, hairline #e0e0e0, ink #222222, muted ink #5c5c5c, accent #7852ee, and filled action violet #6d47e0.
• Platform system UI and monospace font stacks only.
• Filled buttons use white text on violet. Sidebar active links use white text on #8a5cf5; inactive sidebar links use muted gray.
• Cards and screenshot frames use 1px hairlines, compact radii, and app evidence rather than decorative illustration.
• Docs code fences use Expressive Code with github-light and github-dark-dimmed themes on --lapis-surface-1 backgrounds, switching with the site theme.
• The Help and Developer docs graph maps starlight-site-graph variables to the active Lapis token set and the bundled graph plugin’s subdued node/link language without importing app runtime CSS. Hovered labels use the primary violet separately from highlighted links, base labels stay compact for the sidebar, and fullscreen mode increases the graph scale to better use the expanded canvas.

Media Capture

• pnpm media:site prepares e2e-vault-temp, boots the workspace dev server, creates a fresh browser vault, seeds the tracked e2e-vault dataset into it, restores .obsidian/workspace.json, captures the landing hero from that default layout, and for each view-specific still runs Workspace: Focus Leaf (app:focus-leaf) before screenshotting the full .workspace shell.
• Generated assets live under packages/lapis.md/public/media/.
• Landing stills use predictable landing-*.png filenames; plugin/help stills use help-*.png including help-notebook-view.png, help-notebook-dependencies.png, help-notebook-packages.png, and help-notebook-variables.png; workflow motion assets use help-*.gif filenames.
• Keep still screenshots roughly 1280-1440px wide and keep animated GIFs short, dark-theme, and around 960px wide so the site ships optimized but readable media.

Domain Split

Deployment

Production hosting is Cloudflare Pages at https://lapis.md.

The publish workflow runs on pushes to main that touch packages/lapis.md/ or the publish workflow file. It checks the site package, builds static output, and deploys the prebuilt dist/ directory with Wrangler in the same job. Manual reruns are available through workflow_dispatch.

Forgejo repository secrets required for deploy:

• CLOUDFLARE_API_TOKEN — API token with Cloudflare Pages → Edit for the account
• CLOUDFLARE_ACCOUNT_ID — account ID that owns the Pages project

Create the Cloudflare Pages project named lapis-md, attach the lapis.md custom domain in the Pages dashboard, and point DNS at Cloudflare before the first automated deploy.

Production publication runs through Forgejo (.forgejo/workflows/publish-lapis-md.yml). Source code lives at code.ju.ma/lapis-notes/lapis.

Validation

pnpm --filter @lapis-notes/lapis.md check:all

Root pnpm check:all includes this package through Turbo. The site check runs pnpm --filter @lapis-notes/lapis.md api-docs:check before astro check; that non-mutating verification regenerates the API docs in a temp workspace, compares them against the checked-in src/content/docs/developers/api-reference/ tree, and fails on drift. TypeDoc still reads typedoc.tsconfig.json, which extends the API dev config so the docs pipeline resolves @lapis-notes/* imports from source and passes on a clean checkout without prebuilding UI or API dist/ output.

Troubleshooting

Workspace App (@lapis-notes/workspace)

The workspace package is the visible renderer shell. It composes the API runtime, UI primitives, and plugins into the full note-taking application. It does not replace the runtime layer; it stages and renders it.

The installable browser/PWA host now lives in @lapis-notes/web. The approved desktop direction keeps this package as the shared renderer layer inside future host shells, while host-specific capability bridging, installability, and community-plugin isolation stay outside this package. See ADR-001: Plugin Runtime Rework.

Source: packages/workspace/src/

Boot Sequence

Shared Bootstrap (src/lib/components/app/bootstrap.ts)

Exports mountWorkspaceApp() and the shared bundled core-plugin list used by host packages. The bootstrap helper loads fonts (Shantell Sans variable, Source Code Pro), shared app CSS, and the bundled plugins: WordCount, LangCode, MarkdownPlugin, CsvPlugin, FmodePlugin, HistoryPlugin, FileExplorerPlugin, TagsPlugin, @lapis-notes/notifications, SearchPlugin, TasksPlugin, and BasesPlugin. AppPlugin is still registered by App.svelte as a required workspace-local core plugin. First-party plugin app.css sources are registered only for bundled plugin entries, so PluginManager injects those styles on enable and removes them on disable. The notifications plugin is required because it owns app-level notification and progress UI. Canvas, Graph, Markdown Lint, PDF, Slides, Telemetry, Docs, and Notebook are external official plugins: the workspace no longer imports, registers, scans CSS for, or bundles them by default. When one is installed from the verified official registry, its files load from /.obsidian/plugins/<id>/, its enablement remains compatible with community-plugins.json, and settings/search group it under Core plugins because installed-plugins.json records provenance: "official".

The shared shell also exposes a DOM-level hint-target contract for bundled keyboard navigation overlays. Workspace chrome that wants to participate in fmode-style navigation marks visible interactive elements with data-hint-target plus related data-hint-* metadata, and the runtime exposes those visible targets through Workspace.getVisibleHintTargets() rather than requiring the plugin to understand every shell component directly.

The shared src/app.css entrypoint declares a Tailwind source graph that includes workspace-local renderer source alongside API, UI, and bundled plugin source. It imports tailwindcss first, so Tailwind Preflight remains the shared renderer reset layer before the shared theme and workspace-shell overrides apply. Bundled plugin-specific app.css files are imported as inline CSS strings by the bootstrap module and handed to the plugin manager instead of being imported into the global workspace stylesheet, so local bundled-plugin style edits still hot-reload from source while plugin chrome follows enable/disable lifecycle. External official plugins are not listed in the workspace Tailwind source graph; installed official and community plugins load their packaged styles.css from /.obsidian/plugins/<id>/ when enabled. Host packages that import this stylesheet therefore emit the same workspace utility classes, including arbitrary sidebar sizing utilities, neutral hover-token classes, and workspace-owned CodeMirror lint chrome, as the standalone workspace shell.

The workspace Vite dev server now resolves its direct first-party workspace dependencies from their src/ trees instead of their published dist/ exports, including @lapis-notes/bases. It also aliases the shared UI CSS entrypoints (@lapis-notes/ui/theme.css, styles.css, and CodeMirror autocomplete CSS) to packages/ui/src/lib so live palette edits cannot be masked by stale local dist/ output. The dev esbuild target is pinned to es2022, which forces decorator-bearing package code such as Bases’ PEaQL table definitions to be transformed before the browser evaluates it. That gives Vite a live module graph for shared package edits, including package-local $lib imports, without the old rebuild watcher for package dist/ artifacts. The workspace Vite config also installs the generated plugin-host import-map plugin, which injects app-owned renderer import maps for public host wrapper modules under /__lapis/host/ in dev and emitted wrapper assets in production.

Because the module graph is evaluated before the Svelte shell exists, the bootstrap helper now buffers timing measurements so pre-mount import and mount delays can be replayed once telemetry becomes available.

Dev Entry Point (main.ts)

The workspace package still carries a thin browser dev-shell entry point, but it now just calls mountWorkspaceApp(document.getElementById("app")!) with the browser blob-backed plugin asset server used by dev and Playwright. The asset server reads verified installed-plugin metadata from the active vault and serves hash-checked object URLs for official ESM plugin entries without relying on the web package service worker. Host-specific browser responsibilities such as service-worker registration and install prompt handling live in @lapis-notes/web. E2E bootstrap may inject plugin distribution options before mount so local signed registry fixtures can replace the embedded official source during tests.

Vault Bootstrap (VaultBootstrap.svelte)

Phase-based state machine:

1. “loading” — Attempts to restore a previous vault profile from CurrentVaultProfile.
2. “choose” — Browser and desktop hosts now share the same branded two-column chooser: host-specific vault actions on the left and recency-ordered recent projects on the right, backed by the shared saved vault-profile store in IndexedDB (web) or the desktop bootstrap KV store (Electron). Browser actions are New Browser Vault (OPFS), Open Demo Workspace, Open Local Folder (File System Access), and New Legacy Vault (Lightning FS). Desktop actions are Create New Vault, Open Demo Workspace, and Open Vault for native folder vaults. The demo action opens a stable built-in sample vault from a generated bundle of the repo e2e-vault fixture, excludes plugin-test, strips stale .lapis/cache generated state, and marks the saved vault profile as a demo profile so reset flows can target it later. Normal demo opens are idempotent: after vault-session/database ownership is resolved and before App.svelte mounts, bootstrap validates the required fixture files, repairs missing or outdated fixture content, and preserves extra user-created files unless the user runs the explicit reset command. When no saved or recoverable vaults exist yet, the chooser defaults to a create-first landing on both hosts, promoting the create action and switching the hero copy from Open a vault to Create a vault; once recent or recoverable vaults exist, it falls back to the normal open-vault landing. Recent-project rows expose rename, copy vault id, remove-from-list, and browser-local delete-vault actions on all hosts; move and reveal actions remain desktop-only. Delete vault on browser OPFS and legacy profiles permanently clears stored vault files, generated state, and the saved profile after a confirmation dialog that requires typing the vault display name. Recoverable orphan OPFS rows expose the same delete flow using the humanized vault label. Bootstrap appearance (light/dark/system) is editable from the chooser settings dialog on both hosts. Desktop hosts restore legacy tauri-folder profiles through NativeDesktopVaultAdapter and migrate them to desktop-folder on open.
3. “permission” — Requests read-write permission for File System Access handles.
4. “blocked” — Fallback state used only when a competing tab already owns the per-vault SQLite OPFS database and delegation is unavailable.
5. “ready” — Transitions to App.svelte.
6. “error” — Error display.

On the Electron desktop host, the choose phase uses the shared chooser shell described above with desktop-specific folder actions, inline recent-project rows, a command-palette-style View all recent-project search, and a bootstrap-local settings dialog for light/dark/system appearance. Each inline recent-project row also includes a per-vault actions menu for copying the saved vault id, renaming the stored vault alias used by app URLs, moving the native vault folder, revealing the vault root in the host file manager, and removing the saved recent-project entry. The chooser appearance is driven by a desktop-global bootstrap setting stored alongside those saved profiles so the page can match the last selected app appearance before App.svelte mounts and before vault-scoped configuration loads.

On browser/PWA hosts, the same chooser shell loads recent projects from the renderer IndexedDB vault-profile store, applies bootstrap appearance when entering the chooser, and creates multiple isolated OPFS vaults under vaults/<vaultId>/ or multiple legacy vaults backed by per-profile Lightning FS IndexedDB stores. Legacy profile id lightningfs-default continues to use the original lightning-fs-1 store for backward compatibility. When OPFS vault directories exist without a matching saved profile, the chooser lists them under Recoverable vaults so users can re-register the profile without deleting stored files.

When browser SQLite is available, the bootstrap shell now coordinates per-vault ownership before it mounts App.svelte, but it defers the expensive appDatabase.open() work until the mounted shell begins background metadata hydration. The owning tab still becomes the only tab that starts local SQLite work, while competing tabs prefer to mount the normal app shell with a delegated AppDatabase proxy that forwards requests to the owner tab over BroadcastChannel and retries takeover in the background instead of silently opening a separate IndexedDB generated-state store. The blocked state remains as the fallback when delegation is not available. On the Electron desktop host, the same bootstrap path resolves the session runtime to electron-desktop, skips the browser-only SQLite coordination states, and hands the shared app shell a native folder adapter plus native AppDatabase bridge instead.

Vault bootstrap also records timing measurements around profile restore, profile opening, and vault-session creation so the diagnostics view can separate “time before any UI mounts” from “time spent resolving the active vault and app database”.

App Initialization (App.svelte)

Before the startup task runner begins, the shell installs a browser telemetry controller onto app.telemetry. The controller uses OpenTelemetry spans for app-owned lifecycle work plus browser web-vitals and longtask observers when enabled, and it can swap between a live browser exporter-backed implementation and a no-op implementation without changing the app.telemetry reference. Bootstrapping still seeds the controller from window.__LAPIS_TELEMETRY__ or matching localStorage keys (lapis.telemetry.enabled, lapis.telemetry.otlp.endpoint, lapis.telemetry.debug, lapis.telemetry.webVitals, lapis.telemetry.sampleRate, lapis.telemetry.slowSpanThresholdMs, lapis.telemetry.persistDiagnostics). The external official lapis-telemetry plugin, when installed and enabled, owns the diagnostics UI plus persisted telemetry settings, mirrors effective values back into those boot keys, and reapplies them on plugin load through its Core plugins settings surface. When the plugin enables diagnostics persistence, the controller also stores the recent traces, slow spans, measurements, and web-vitals buffer in vault-scoped IndexedDB state so the diagnostics view can restore them after an app restart. The controller keeps an in-memory working buffer so the installed telemetry plugin can show recent slow traces in a sortable, filterable, paginated table with a single segmented trace summary bar, plus a dedicated trace-detail header, stacked waterfall rows, a selected-span sidebar, and vitals without needing an external backend.

On startup, App.svelte first flushes the buffered bootstrap measurements into app.telemetry, then records the existing task-runner spans. This keeps the diagnostics timeline continuous across entry import, vault bootstrap, and sequential workspace initialization. The shell registers appearance, editor, files, and workspace configuration schemas before plugin loading; the workspace schema includes workspace.editorAssociations, a record map from VS Code-style glob patterns to registered editor-view IDs, plus the first mobile-shell configuration keys under workspace.mobile.*.

App.svelte also owns the workspace display-mode provider in the renderer package. It reads workspace.mobile.mode (auto, always, never) plus workspace.mobile.breakpointPx, observes the current viewport width, computes the effective workspace display mode (desktop or mobile), and updates app.workspace.displayMode through the API package’s non-persisted display-mode helpers. Changing display mode is presentation-only: it does not mutate or save workspace.json on its own.

The shell now also stamps the document root with data-runtime, data-engine, data-os, and native data-arch selectors derived from the active vault session, native desktop bridge platform metadata when available, and browser platform detection as a fallback. Workspace and host CSS can use that single root seam for WebKit-, Blink-, OS-, or architecture-specific regressions instead of scattering browser checks throughout individual components. The same root seam now exposes data-workspace-display-mode and data-workspace-mobile-requested-mode so shell-specific styling can react to the effective and requested mobile mode without asking individual leaves to know about viewport policy.

Sequential TaskRunner executes:

1. Loading file system → app.vault.load()
2. Loading configuration → app.configuration.load() plus app.commands.loadHotkeys() for vault-scoped shortcut overrides
3. Loading core plugins → Instantiates all core plugins
4. Loading plugins -> registers the workspace CommonJS dependency resolver, registers explicit legacy CommonJS dependency overrides from deps.ts, gives PluginManager the host-provided plugin asset server when one was supplied by the Web/PWA or Electron bootstrap, reads installed plugin provenance, discovers external plugins, activates configured community plugins, and activates configured official plugins as optional core plugins
5. Loading layout → app.workspace.loadLayout()

The loading screen shows the active task plus the ordered startup checklist so users can see which initialization phases have already completed and which are still pending.

Once the shell mounts, App.svelte schedules app.metadataCache.load() on the next animation frame instead of blocking the loading screen on metadata restoration. That background load opens AppDatabase, restores the current metadata snapshot from the app database or portable .lapis/cache/metadata-cache.json backup, falls back to a first-open rebuild when no generated state exists, and notifies metadata-driven features through the existing loaded event when the cache becomes ready. The shell asks the metadata cache to flush any pending snapshot and portable backup write during teardown.

If any startup step fails, the shell no longer leaves the user on a misleading loading screen. It now renders a dedicated startup failure panel that shows the last boot step, the error detail, and recovery actions for reload, resetting the saved workspace layout, entering a session-scoped Safe Mode, disabling notebook execution for the next reload, and rebuilding generated metadata or search state.

Safe Mode state lives in browser session storage instead of canonical vault config, so recovery-only boot policies do not permanently disable plugins or layout restore. The ready shell shows a visible Safe Mode banner that explains which temporary restrictions are active and preserves the last startup failure summary; when a failing community plugin is identified, that banner also exposes a targeted disable action.

When the current session is using delegated SQLite ownership (sqlite-proxy) and a remote metadata snapshot request times out, the shell now warns through logging and continues boot with the legacy snapshot or an empty in-memory metadata cache instead of aborting startup.

Post-load setup:

• Keyboard event handler forwarding to additional overlay scopes first, then intercepting bare Escape for transient workspace focus mode before delegating to the active leaf scope so focused editors do not trap the exit action
• Optional console logger registration when window.__LAPIS_CONSOLE_LOGGING__ or localStorage["lapis.logging.console"] enables it
• Telemetry disposal hook for shell teardown
• Renders: ModeWatcher, Toaster, Tooltip, Commands, plus desktop-only StatusBar and PopoutWindowManager chrome when the effective workspace display mode is desktop

The required notifications plugin renders all app-level notification chrome after plugin activation. It bridges app.notifications to the workspace UI: in-app toast messages, compact progress and bell/count status items registered through app.statusBar, and a scrollable notification center panel toggled by the notifications command surface. The status-bar items keep inline text stable by showing only short task summaries while full progress detail lives in the item tooltip and notification center panel, and active progress items animate their icon as a spinner instead of expanding into a separate status banner. The existing Toaster container remains a renderer dependency, but callers should use app.notifications or the compatibility Notice wrapper instead of importing toast APIs directly.

The app plugin command surface now includes browser-local import and export commands, desktop-folder reveal, a shared About Lapis Notes command, saved workspace layout commands, transient workspace focus controls (Workspace: Focus Leaf for the selected root tab and Workspace: Exit Focus Mode), explicit mobile layout commands (workspace:toggle-mobile-layout, workspace:use-mobile-layout, workspace:use-desktop-layout, workspace:open-mobile-tabs, workspace:open-mobile-search, workspace:open-mobile-left-sidebar, workspace:open-mobile-right-sidebar), the existing metadata rebuild command, a demo-only Vault: Reset Demo Vault command, and a combined generated-state rebuild command that reruns metadata and search repair paths without deleting canonical notes. The mobile layout commands update the shared workspace.mobile.mode configuration or the current mobile page state instead of creating a second workspace layout source of truth; page commands show the existing mobile surfaces only while the mobile shell is active, while the sidebar commands fall back to expanding the corresponding desktop sidebar when the desktop shell is active. The reset command is available only while the active session profile is marked as the bundled demo workspace; it queues a one-shot reset marker, reloads the renderer, and lets VaultBootstrap.svelte rewrite the fixture and prune non-fixture files before App.svelte mounts so live watchers and metadata consumers do not race a full vault rewrite. The About command opens a small branded dialog in the shared renderer shell using the current Lapis logo, shows the app version plus the best available build timestamp, displays a GitHub-style short build commit hash on a copy button that copies the full hash, and offers a dedicated copy-version action. Browser-hosted workspace sessions also register a right-aligned version status item that shows the current app version with an info icon and runs the same About command on click; the item is gated by the runtime.browser context key so it does not render inside Electron desktop sessions.

Settings-target navigation inside an already-open Settings panel updates the selected surface directly instead of toggling the Settings dialog closed and open. Plugin management gear buttons and search result actions therefore keep the panel shell mounted while they switch to the target plugin or schema surface. The same Settings panel uses the shared sidebar provider’s resize state for its navigation column, starting at 14rem and letting the rail update the provider width directly so the content pane remains visible while the navigation width changes. Its modal-scoped resize rail keeps the visible hover/focus separator at 2px while still using the normal shared sidebar drag hit target.

When a user opens a file whose handler is not currently registered, the shared workspace leaf opening path can show an on-demand official plugin install prompt from signed registry contribution summaries. Full Registry V1 uses this for .lapisdoc and .lapissheet: the prompt offers Install and open, calls the distribution manager with requireOfficial: true and enable: true, and reopens the original file after the plugin registers its editor view. Existing registered handlers still win, and failed installs leave the prompt visible with the specific installer error so the user can retry or navigate away.

Saved workspace layouts are Obsidian-style named snapshots stored in .obsidian/workspaces.json, separate from the live session layout in .obsidian/workspace.json. The manage command opens a compact dialog with a name field, Save action, saved layout rows, active-layout badge, relative modified time, per-layout Load, and immediate delete. The load command opens a command-palette-style picker that lists saved layouts with modified time and active state. Loading a saved layout replaces the current workspace tree, saves the loaded snapshot back to the live layout file, and records the saved layout name as active. The Save and load another layout command saves the current tree back to the active saved layout before opening the picker; if there is no active saved layout, it asks the user to save one first.

The vault file watcher ignores generated metadata backup events for .lapis/cache/metadata-cache.json and its generated parent folders before reload handling, so periodic backup writes do not reprocess metadata or reload the active vault.

The shared shell also dispatches app URLs after boot through app.urls. Desktop hosts can deliver queued lapis:// launches through the native bridge, while the browser/PWA host can route installed-PWA web+lapis:// protocol launches through /open?url=... before handing them to the same API service.

When the current session is using delegated SQLite ownership (sqlite-proxy), the status bar shows a built-in icon-only DB Proxy button that opens a short explanatory popover on click. The indicator follows live coordinated-database ownership, so it disappears after the tab finishes taking over SQLite locally.

The shared status bar now renders API-owned declarative items from app.statusBar on both left and right alignment tracks, sorted by priority with stable registration order for ties. Declarative items can mark their icon as spinning while background activity is in progress, and the shared button chrome forwards that state through aria-busy. Declarative buttons expose data-status-bar-item-id for renderer diagnostics and focused Playwright coverage. A dedicated compatibility host remains mounted inside the same shell so imperative Plugin.addStatusBarItem() callers can continue to append raw DOM items without blocking manifest-only or first-party declarative status bar contributions.

This is still the shared renderer boot flow. Host-specific capability bridges, such as the native desktop bridge, can now steer vault bootstrap into a runtime-specific session and provide platform metadata without forking the visible shell. Broader plugin-host selection remains a future renderer-shell responsibility.

Application Layout

App.svelte
├── DesktopWorkspaceShell or MobileWorkspaceShell (one at a time)
│   └── DesktopWorkspaceShell
│       ├── Sidebar.Root
│       │   ├── Ribbon (left icon strip)
│       │   ├── Left Sidebar (TabsSplit)
│       │   ├── Root Split (TabsSplit, center)
│       │   ├── Floating Pane Overlay (WorkspaceWindow -> TabsSplit)
│       │   └── Right Sidebar (TabsSplit)
│   └── MobileWorkspaceShell
│       ├── MobileWorkspaceStage or MobileTabsPage
│       │   └── MobileSidebarToggle + MobileViewActions + MobileFloatingDock (stage mode)
│       └── MobileActionsDrawer + MobileTabsActionsDrawer
├── PopoutWindowManager (desktop mode only)
├── Commands (command palette)
├── StatusBar (desktop mode only)
└── Tooltip (global tooltip handler)

App.svelte branches between shell variants instead of mounting both and hiding one with CSS. That preserves the one-shell invariant for WorkspaceLeaf.containerEl: a live leaf host is mounted in only one renderer shell at a time, avoiding view reparenting bugs when the display mode changes.

MobileWorkspaceShell is the touch-first presentation layer over the existing workspace model. It binds app.workspace.containerEl to a full-viewport mobile shell, removes the dedicated mobile top header, hides the full desktop ViewHeader while mobile mode is active, and relies on the shared editor inline title inside the active view content immediately before the .cm-editor-content editor host so file-backed mobile titles scroll away with the page. The default mobile editor surface remains a single-page active-root-leaf viewport instead of the desktop root tab/split interface. MobileWorkspaceStage mounts fixed-width left and right sidebar panels offscreen and translates around that one mobile leaf page so pointer-driven pan gestures can reveal sidebars without rendering the whole desktop main interface in the center. Horizontal pan gestures can start anywhere on the main stage surface (including mid-screen) to reveal or dismiss mounted sidebars. When a sidebar is already revealed, pointer capture is taken immediately on the close overlay so swipe-to-close stays reliable. The stage defers to scrollable descendants only when movement clearly scrolls that ancestor on the matching axis and the scroller can still absorb more movement there (for example a task Bases .task-bases panel with overflow: auto does not block a horizontal sidebar reveal while scrollLeft is pinned at 0); otherwise horizontal movement crosses a pan threshold and max-angle gate before preventDefault. Touch drags do not call setPointerCapture (scrollable editors steal capture immediately); mouse/pen drags may capture when a sidebar is already open. Mobile leaf surfaces use touch-action: pan-y so the browser keeps vertical pans on scrollable content, switching to touch-action: none on the stage and editor chain while a horizontal pan is active. Active pans listen on document for pointer move/end when needed (touch from pointerdown; mouse only after a horizontal drag commits) so touch drags continue after incidental lostpointercapture events without settling early. Sidebar width is measured via ResizeObserver instead of per-gesture layout reads; scroll-target detection and debug layout snapshots run only after movement crosses the pan slop. Mobile scroll chrome follows native scroll events rather than synthetic touchmove deltas. The stage follows horizontal pointer movement while dragging, clamps between left/center/right snap points, and settles to a resting snap point on release using drag distance and fling velocity so cancelled or vertical-dominant gestures cannot leave an intermediate offset behind. The right sidebar reveal aligns the panel’s right edge to the mobile viewport instead of reserving desktop right-ribbon space, and tapping or dragging the exposed main page closes the revealed sidebar.

Mobile sidebar panels render the selected sidebar child body directly, omit the desktop sidebar tab-header strip, and provide a bottom name-based selector for switching sidebar tabs. Revealed sidebar panels are excluded from stage swipe capture so their toolbar and menu controls remain clickable. A small floating left-sidebar toggle mirrors the floating top-right action cluster derived from the active root leaf’s view.actions; both top controls are mounted inside the translated middle panel and hide when editor scrolling moves down, reappearing when scrolling returns upward. The compact floating dock is also positioned inside the middle panel instead of fixed to the page, hides with the other scroll chrome, avoids reserving a footer-sized content block, and exposes back, forward, left-sidebar search, new-note, main-tab count, and overflow actions; the bottom overflow surface uses a Vaul-backed shared Drawer wrapper; app-owned context, dropdown, and popover menus render through the shared drawer on mobile-width viewports; and the mobile tab viewer limits itself to main/root tabs rendered as compact live preview tiles capped around 176x200, with the title under each preview, activate-on-tap, and top-right close controls. The tabs page has no top heading; fixed bottom controls keep the open-tab count in the center, Done at bottom right, and a MobileTabsActionsDrawer for New Tab, Undo close tab, and Close tabs actions. The mobile shell mounts settings dialog content and a hidden status-bar compatibility host so desktop-era settings and imperative status-bar plugins remain available without a visible mobile status bar. The one-shell invariant still applies: the mobile editor page, mobile tab previews, and sidebar reveals are mutually exclusive leaf-host surfaces, so a WorkspaceLeaf.containerEl is mounted in only one place at a time.

Sidebar Layout (sidebar-root.svelte)

Three-column layout using Sidebar.Provider + Sidebar.Inset + Sidebar.NestedProvider:

• Left: Ribbon + left split (collapsible).
• Center: Root split (dynamic width based on sidebar sizes).
• Floating pane overlay: viewport-level floating-pane host that renders persisted WorkspaceWindow containers on the named workspace floating layer while leaving uncovered areas pointer-transparent so existing root drop targets still receive drag/drop. Floating pane content is wrapped in the same workspace shell styling context as the main split so shared top-tab and stacked-tab selectors apply consistently inside floating windows.
• Right: Nested sidebar (collapsible).
• Drag-enabled rails on left/right edges. The rail separator keeps its hit area but grows from a 2px neutral line to a 4px var(--interactive-accent) line on hover and focus-visible.

Left Sidebar (sidebar-left.svelte)

Renders ribbon items (toggleable), TabsSplit for left workspace views, and shell controls in the footer. Browser-local and desktop vault sessions now share a footer vault switcher trigger showing the current vault name, a dropdown of up to eight recent vaults, and a Manage Vaults action that returns to the chooser while preserving the existing settings button. The bundled file explorer now mounts immediately and shows an “Opening vault” loading state while vault contents are still loading so the left sidebar does not appear blank during bootstrap, and it repopulates the left sidebar with the default explorer leaf when restored layout state would otherwise leave that side dock empty.

The file explorer toolbar exposes create-file, create-folder, filename sort, auto-reveal, and expand/collapse controls. The sort menu supports filename ascending and descending modes while preserving the existing folder-before-file grouping inside each folder.

When the left sidebar is collapsed, the shared sidebar rail now offsets its visible hit target by the desktop titlebar clearance token so the left-edge reopen affordance clears the native macOS traffic-light cluster instead of starting directly beneath the ribbon/titlebar seam.

Right Sidebar (sidebar-right.svelte)

Simple sidebar wrapping TabsSplit for the right workspace split. The root container uses overflow-hidden so the shared rail hover/focus line is clipped to the pane edge the same way as the left outer sidebar.

Tab System

tabs-split.svelte — Recursive Split Layout

Renders a Resizable.PaneGroup (horizontal or vertical based on split type). Recursively renders child splits or tab groups. Empty state shows a drag hint. Emits app.workspace.requestSaveLayout() on pane resize. Manages pane sizes via view.sizes array. Split handles keep their existing drag targets while the visible separator line thickens from 2px to 4px and switches to var(--interactive-accent) on hover and focus-visible.

Empty View

The workspace package owns the app-facing empty-tab renderer used for normal new tabs and missing-view fallbacks. Normal empty tabs keep the standard centered create/open/recent actions. When the workspace falls back because a requested view type is no longer registered, the empty view reads state.__missingViewType, shows that id in the tab title, and swaps the center content for a dedicated unavailable-plugin message with a close action.

tabs-top.svelte — Horizontal Tab Bar

Top tab strip with:

• Scroll container for overflow.
• Top tab label icons from each view type.
• Markdown tabs allow plugin-provided CSS overrides for icon display in top tabs.
• Tab width: max - (count × 40px).
• Close on middle-click.
• Drag-drop reordering.
• The reorder marker aligns to the visible tab edge and animates briefly as the drag target moves between tabs.
• On the Electron desktop host, native macOS window dragging is restricted to non-interactive chrome instead of the tab strip itself so HTML5 tab drag-drop and drop indicators still work inside the frameless shell.
• Active tab highlight.
• Add (+) button for new tabs.
• Respects editor.alwaysFocusNewTabs config.
• Each leaf renders its ViewHeader above a flexed view-content region so file-backed views stay confined to the remaining tab body instead of stacking a second full-height pane under the header.

Double-clicking a root top tab now enters a transient focus mode for that tab group. The promoted group is rendered as a fixed shell layer spanning the full app chrome across both sidebars without moving the leaf into a floating pane or mutating persisted layout. The focused strip adds a visible Exit focus mode button, and global Escape routing leaves focus mode even when the active leaf editor would otherwise consume the key.

tabs-stacked.svelte — Stack Menu

Dropdown menu showing all tabs with toggle between stacked/regular view.

The stacked header bar now participates in the same desktop drag-region contract as the top and sidebar tab headers: the non-interactive bar surface is draggable on desktop hosts while the add-tab, overflow, and sidebar-toggle controls stay no-drag so their click handling continues to work.

Stacked tab headers share the same transient focus-mode behavior as top tabs: double-clicking a stacked root tab promotes that tab group across the full shell, preserves the in-place leaf/view state, exposes the same explicit exit control, and leaves overlay menus or popovers above the focus surface through elevated shell z-index rules.

tabs-sidebar.svelte — Sidebar Tabs

Vertical toggle group with icon + label per top-level sidebar child. A normal WorkspaceLeaf keeps the compact icon tab behavior and view context menu actions. A WorkspaceSidebarGroup renders as one top-level sidebar tab and expands into a vertical stack of collapsible child panels. The expanded panels are arranged in a vertical Resizable.PaneGroup, so users can resize the open panel bodies and the workspace saves the resulting proportions on the group. Each panel mounts the real leaf view, stretches the expanded content area to the available pane height, shows the leaf icon/title plus item-view actions, and keeps view context-menu hooks available from the panel header. The chevron and the panel title both toggle collapse, collapsed panels shrink down to the header row so their space is returned to expanded siblings, and when every panel is collapsed the headers pack together at the top of the stack instead of splitting the remaining height. Grouped sidebar tabs also preserve the shared sidebar toggle button in the header, so the active grouped tab can still collapse the left sidebar without switching back to a normal tab first. Sidebar tab buttons use --background-modifier-hover for hover feedback and --background-modifier-active-hover for selected state, while grouped panel headers use --sidebar-accent so both dark and light sidebars keep visible hover contrast.

Sidebar group menus support renaming the group, changing the icon, managing visible panels, ungrouping back into normal sidebar tabs, closing hidden panels, and closing the group. Normal sidebar tabs can be converted into a group through a lightweight metadata dialog, and the group metadata flow now uses the shared icon picker instead of a freeform icon text field. The visible-panels dialog toggles persisted hidden leaf IDs without destroying the underlying leaves.

Sidebar shell styling is placement-aware rather than view-type-specific. When leaves or tab groups are moved into a sidedock, workspace-shell.css applies dock outer borders, pane separators, tab/header borders, grouped-panel borders, and collapsed-sidebar boundary lines from sidebar boundary variables so a sidebar-hosted pane stays visually separated even when its view body uses the main editor background. Top tab containers, filler areas, overflow controls, and active tab wrapper outlines stay on the original tab-shell elements while resolving those colors through the tab or sidebar boundary tokens.

Installed browser PWAs that run with Window Controls Overlay use the same sidebar tab markup, but workspace-shell.css now keeps root top-tab and stacked-tab headers in their normal pane flow instead of pinning them to the viewport safe rectangle. Each root header measures how much the host-reported blocker area overlaps that pane-owned titlebar surface, reserves only the overlapping left or right inset as internal padding, keeps the non-interactive header surface draggable, and leaves interactive descendants no-drag. Sidebar headers now also feed that measured overlap into the split-scoped sidebar padding rules, so left and right dock tab rows can reserve more than the static macOS traffic-light or Windows/Linux caption-button gap when the reported blocker region is larger than the baseline safe-area token. The shared shell still expands the sidebar tab-header flex basis by the host-provided title-bar top inset, keeps the inner sidebar tab row at a normal minimum header height, and assigns the sidebar tab buttons explicit nav-item foreground colors so the left and right dock SVG icons stay visibly painted in collapsed and expanded overlay states instead of relying on inherited text color. The left dock reserves only the macOS split-scoped traffic-light gap after subtracting the ribbon width, the right dock reserves the Windows/Linux caption-button inset on the inner tab row, the narrow ribbon is not padded by the full macOS traffic-light width, and the unified bottom border of the WCO title-bar strip is painted by a 1px :root::before divider at --workspace-safe-area-top rather than per-bar border-bottom rules (which would otherwise show through under the active top-tab notch). When the native title bar is visible in a PWA host (data-pwa-titlebar-hidden absent), the same border-bottom treatment applies only to sidebar-tab and stacked chrome-header rows, not the top-tab outer bar, so the active-tab notch continues to clip the inner .workspace-tab-header-container border cleanly. Collapsed docks render matching 2px ::after/::before boundary lines below the header zone using --workspace-sidebar-pane-border so body-zone seams stay aligned with the shared 2px sidebar-rail and resizable-handle affordance. Only the top-tab and stacked chrome-header rows raise their z-index to keep painting over neighbour chrome; the sidebar bar inherits its natural stacking order so resizable pane handles and dock layers paint cleanly above it, and [data-sidebar="rail"] is offset by calc(-1 * var(--workspace-safe-area-top)) so the collapsed-sidebar reopen rail extends up into the safe-area strip.

packages/workspace/e2e/pwa-title-bar.spec.ts now clones the production WCO media rules, injects simulated native-control blocker rectangles, and asserts that pane-owned top titlebars stay aligned with their host panes while interactive controls never overlap those forbidden regions on macOS and Windows, alongside sidebar painted-icon contrast, split-scoped inset checks, blocker-based non-overlap assertions for sidebar tab buttons, WCO border checks (including a :root::before divider probe, an outer-bar border-bottom guard against active-tab notch leakage, sidebar-rail and collapsed-dock boundary width probes, and a sidebar-rail extends-into-safe-area assertion), an elementsFromPoint probe asserting the sidebar dock radio is the topmost paint at its own centre, a bundled demo-workspace (e2e-vault) WCO seam regression, and reference screenshots of the macOS top-left/top-right and Windows top-right corners under e2e/__screenshots__/pwa-title-bar.spec.ts/.

Workspace Playwright coverage now exercises the grouped sidebar path in the real renderer shell: grouped panel rendering, group menu and visible-panel basics, grouped-tab sidebar-trigger visibility, top-level sidebar-tab pointer reordering, title-toggle collapse behavior, all-collapsed header packing, vertical panel resizing, serialized panel-size state, expanded content filling the available panel body, and pointer-driven floating-pane creation for grouped sidebar panels.

Separate workspace Playwright coverage also exercises pen and touch layout drag/drop in the live shell, including top-tab reordering, split drops, grouped-sidebar panel reordering, drag-out floating panes, floating-pane move/resize/collapse/minimize/maximize/close, floating stacked-tab styling, floating markdown-link local navigation, popout theme-color mirroring, menu-driven float actions, reload-time bounds and collapsed/minimized state persistence, redock, pointer cancellation, touch long-press activation, flick cancellation, and jitter-under-tolerance behavior, alongside dark/light hover contrast for sidebar and workspace chrome controls, notebook-owned runtime and output status messaging, a Chromium-scoped daily-use journey that boots an OPFS vault, creates and renames notes, verifies search indexing, executes a notebook, reloads the shell, and confirms the renamed note and restored notebook outputs survive restart, and a fresh-browser app-boot smoke path that reports startup checklist and shell-readiness state when boot times out or surfaces the startup-failure panel. The workspace-shell visual baseline forces light mode before screenshot capture so local OS color-scheme preference does not change the committed snapshot target.

Workspace Vitest coverage is supported through the package-local vitest.config.ts, which resolves first-party packages to source and provides jsdom browser shims for renderer-only helper imports. pnpm --filter @lapis-notes/workspace check:all runs static validation (format, svelte, types, lint). pnpm --filter @lapis-notes/workspace test runs the full Vitest suite. pnpm --filter @lapis-notes/workspace check:unit remains a focused unit gate for plugin feature diagnostics, settings search, and the CommonJS dependency resolver when you want that narrower test subset directly. pnpm --filter @lapis-notes/workspace test:e2e:official-plugins runs the local official plugin install matrix against a signed fixture generated by root pnpm test:official-plugins; it installs every external official plugin through the real registry installer, verifies default enablement/provenance/runtime diagnostics/reload persistence, and performs one runtime assertion per plugin.

Dynamic width: calc(var(--sidebar-width) - var(--ribbon-width)).

Sidebar-tab reorder markers align to the visible tab button edge and animate briefly as the drag target moves between tabs.

Grouped sidebar drag/drop extends the shared workspace layout drag model: top-level group tabs can be reordered with normal sidebar tabs, grouped panels can be reordered vertically, leaves can be dropped into a group, and grouped leaves can be moved back to normal sidebar tabs.

The app shell now also supports in-app floating panes. Each floating pane wraps a persisted WorkspaceWindow split tree in dedicated overlay chrome above the full workspace interface, supports focus/z-order changes plus move, resize, collapse, minimize, maximize, restore, and close interactions, and reuses the same tab/split drop targets for redocking. Floating pane tab content keeps the workspace shell class context, so stacked tab headers keep the same vertical styling as stacked tabs in the main center split. Collapsed and minimized pane states persist with workspace layout JSON, minimized panes render as a bottom-center restore stack, and maximized panes are transient session state that covers workspace chrome until restored. Dragging a top tab, stacked tab, sidebar tab, sidebar group, or grouped sidebar panel out of all registered workspace drop targets now creates a floating pane instead of silently ending the gesture. Top-tab overflow menus, tab context menus, sidebar tab context menus, grouped-panel context menus, and command-palette commands expose the same floating and supported-host popout actions.

Floating-pane chrome now owns a named viewport-level overlay layer above the surrounding sidebar shell so collapse, restore, maximize, minimize, and close controls remain the browser’s top pointer target even when an expanded right sidebar is present. Maximized panes use a higher in-overlay layer while staying transient session state, reserve the desktop macOS traffic-light safe area on the left side of their header, and keep that non-interactive header surface available for native desktop window dragging while the toolbar controls remain explicit no-drag targets. Shared hover-card previews also render above floating panes, so markdown link previews are not hidden under floating window chrome.

The same WorkspaceWindow model now also backs true host popouts on supported renderer hosts. openPopoutLeaf(), moveLeafToPopout(), moveWorkspaceChildToPopout(), and paneType=window app URLs request a separate browser or Electron popup window through a host capability, mount the recursive TabsSplit tree into that document, mirror theme classes, titlebar-derived theme-color metadata, stylesheet, and plugin CSS changes into the secondary head, and register popup-scoped keydown and focus listeners so command routing and active-leaf tracking stay attached to the popout document. On desktop-styled macOS hosts, the leftmost popout tab header now reserves the full traffic-light safe area for both top and stacked tab variants so the first tab never renders beneath the native window controls. Closing the host popup removes the corresponding WorkspaceWindow from layout state and persists the cleanup. Unsupported hosts still surface the shared explicit popout error instead of silently converting the request into a floating pane.

Popup-owned trigger overlays such as the tab overflow menu now inherit their portal target from the shared UI primitives, which default to the trigger element’s ownerDocument.body. That keeps popup menus attached to the popup host without per-call-site portal wiring.

Popup shells also participate in the shared command-host model rather than forwarding palette state back to the root renderer. The workspace tracks a focused host id for the root shell and each WorkspaceWindow, the root app shell mounts the palette for WORKSPACE_ROOT_HOST_ID, and popup shells mount their own inline palette surface inside the popup document. Mod+P inside a popup therefore opens and executes against that popup’s leaf scope instead of rendering into the parent window.

The renderer still computes drop geometry and indicator placement locally, but committed layout mutations now route through shared Workspace helpers instead of mutating the split tree directly inside Svelte handlers. Top-tab reorder, content-area tab drops, split drops, grouped-panel reorders, grouped-panel ingestion, and top-level sidebar-tab moves all emit cancelable workspace lifecycle events before mutating layout and finish with one committed layout-change event tagged with source: "drag-drop".

DragState now resolves workspace layout DnD through auto, pointer, and html5 modes. Desktop mouse drags keep the existing HTML5 path and drag-image fallback, while pen and touch drags use pointer-event sources, registered drop targets, elementsFromPoint() target resolution, and a renderer ghost that does not depend on DataTransfer. Touch drags use a hold delay plus pre-activation tolerance so quick flicks cancel without mutating layout, while held drags can still reorder tabs, split panes, move sidebar tabs, reorder grouped sidebar panels, and float dragged items when no registered workspace drop target accepts the gesture.

On the Electron desktop host, the sidebar tab rows and drop targets are kept out of native -webkit-app-region: drag zones so dragging a sidebar tab into another pane still reaches the renderer drag-drop handlers.

tabs-drop.svelte — Drop Zone Handler

Tracks drag position with 4-edge threshold detection. Visual feedback (blue highlight). Handles leaf and file drops. Auto-selects tab after 2-second hover. Before showing an overlay, it asks the shared workspace API whether the drop target should be exposed by firing layout-will-show-overlay; committed center and edge drops then call shared workspace helpers so drop cancellation, split creation, and final layout persistence follow the same model-level path as tab reorder.

On the Electron desktop host, internal tab/file drags use a renderer-supplied drag image and force a move drop effect so the shell does not fall back to the native copy badge while dragging between panes.

tabs-move.svelte — Inline Drop Indicator

Shows left/right drop zones between tabs for reordering and drives a shared animated edge marker for top and sidebar tab strips. Indicator eligibility is gated through the shared workspace overlay event path, and accepted tab or sidebar-group reorders delegate to Workspace.moveWorkspaceChildToTabIndex().

leaf.svelte

Mounts a leaf’s view by injecting leaf.containerEl into the DOM via a Svelte action. Re-renders on leaf.id change.

view-header.svelte

Tab header with:

• Back/forward navigation buttons.
• Breadcrumb trail (file path with hover reveal).
• Inline file rename (editable title) that truncates with ellipsis when the center header space is narrower than the pane actions and now delegates through app.fileManager.renameFile() so note-link rewrites use the shared link formatter.
• Context menu: split down/right, close.
• Ellipsis menu button.

View-header buttons and breadcrumbs are also one of the initial shell surfaces that opt into the shared hint-target metadata used by the bundled fmode plugin.

Command Palette (commands.svelte)

• Bound to the shared host-aware command-manager state in app.commands.
• Filterable command and file lists ranked with the shared UI Fuse.js helper while bits-ui command filtering stays disabled.
• Closing the dialog clears the previous input so reopening starts from an empty query.
• File search mode: > prefix switches to vault file search.
• Hotkey display with platform-aware Unicode symbols (⌘, ⌥, ⇧, etc.) sourced from effective command hotkeys, so custom overrides and explicit unbindings match runtime routing.
• Text highlighting on matches.
• Command labels parse VS Code-style icon tokens through CodiconLabel: codicon font for $(play), registry SVG for $(lucide:file-text), codicon-first fallback to registered icons for unqualified names, and literal text for unknown or malformed tokens.

The root shell still uses the normal overlay path, but popup shells render the command palette inline inside the popup document rather than relying on a cross-document portal. That keeps palette focus, keyboard handling, and command execution attached to the window host that opened it.

command-files.svelte

Standalone file search dialog with icon + path display. Closing it also clears the previous query.

Configuration UI (configuration.svelte)

• Obsidian-style sidebar nav with flat groups: app-owned Options, then plugin settings surfaces under Core plugins and Community plugins.
• Scrollable content area with dynamic form generation from JSON schemas.
• The Plugin registry tab is the registry-facing plugin management surface. It keeps legacy Core Plugins and Community Plugins tabs available during the V1 transition while adding Installed, Browse, Updates, and Sources views backed by app.pluginDistribution. The tab labels installed official provenance from .obsidian/installed-plugins.json separately from manual community plugins discovered by PluginManager, shows the locked official registry source, and renders through shadcn-backed tabs, buttons, items, badges, and alerts. Browse results render as a denser responsive card grid that can use three columns at full settings width; cards keep scan metadata minimal with version, official status, bundle size, and latest-release update time when the verified detail record provides a releasedAt timestamp, while platform, category, install-state, and other badges move to the detail view. Card details open a full settings-width modal whose resizable left sidebar preserves the current filtered Browse result set while the main pane swaps between plugin README/detail content, including the verified bundle size. README markdown is fetched from the registry-hosted markdown artifact and rendered through the app markdown preview component so registry documentation follows normal markdown preview styling. Registry catalog refresh uses the Refresh button’s spinning icon as its only inline loading affordance rather than adding a separate progress banner. A header action lets users install a local .lapis-plugin file through the same signed official bundle verification path as registry installs, including API-side worker verification on web hosts when available. Install and update actions keep the initiating button busy-disabled, but live task state is reported through app.notifications: the status-bar item stays compact with the plugin task title and percent when download bytes are known, while the notification center shows detail text, the progress bar, and the Cancel action. The settings panel does not render a separate install-progress panel. Registry fetch and install failures appear as destructive alerts and notifications instead of hidden text fields, while user-cancelled installs do not become destructive registry errors. Installed official rows show the verified release bundle size when detail metadata is available and otherwise fall back to summing recorded installed files. The Updates view distinguishes compatible official updates, incompatible latest releases with reasons, and revoked installed official versions that can be disabled or updated to a compatible replacement; update rows include the target release bundle size.
• When a schema expands to exactly one nested subgroup, the visible settings heading keeps the schema’s own title instead of replacing it with the subgroup key.
• Declarative schemas render enum selects, enum-array multi-selects, range sliders, color pickers, and nested object-group headings; unsupported shapes fall back to an Edit in app.json button that opens the vault configuration file in a centered in-app floating editor pane.
• Schema category headings render outside the setting rows, and each category’s generated rows sit inside a rounded, subtly tinted panel with internal dividers and spacing between categories. Row labels use the setting title without repeating the category breadcrumb.
• Record-object schemas render as editable key/value tables. workspace.editorAssociations uses that control with glob-pattern keys and a value dropdown sourced from the live Workspace.editorViews registry while preserving saved values for disabled or missing views.
• Settings writes surface schema-validation failures through the normal interaction path instead of silently accepting malformed values.
• The settings dialog uses a narrower navigation rail and lighter content padding so the form pane uses more of the available width.
• On small viewports, the settings content exposes an icon-only top-left sidebar trigger so the shared sidebar provider can reopen the settings navigation sheet without changing the selected settings surface.
• The settings sidebar includes a command-palette-style search field above the flat navigation. Non-empty queries keep the normal sidebar visible and replace the main settings pane with fuzzy-ranked, grouped result cards built from schema-backed settings, app settings tabs, plugin rows, plugin manifest metadata, plugin diagnostics/features, and declarative configuration metadata. Results highlight matching text, then navigate to the canonical selected surface for the matched schema row, settings tab, or plugin row without mounting hidden imperative tabs for scraping.
• Settings content renders only the selected surface; schema sections are not used as recursive sidebar nodes and scroll position no longer drives nav selection.
• Reacts to config/schema updates, including file-link formatting controls exposed through the shared files.links.* schema.

Hotkeys Tab (hotkeys-settings.svelte)

The app-owned Options → Hotkeys page lists registered commands from app.commands, filters by text or captured pressed-hotkey tags, and can show only commands with an effective binding. The search input includes the capture control: clicking the keyboard icon swaps it for Press hotkey, consumes keydown events while active, exits on Escape, and commits captured shortcuts as removable tags after an idle gap. Entered search text shows an in-input clear button. Each row displays current bindings, Blank for unbound commands, plus/remove/reset controls, and conflict diagnostics for duplicate shortcuts. Edits call the CommandManager hotkey override API, persist to .obsidian/hotkeys.json, and update runtime routing without a reload.

Core Plugins Tab (core-plugins.ts)

Lists bundled plugins and installed official plugins with inline manifest description metadata. Non-required bundled plugins and installed official plugins can be enabled or disabled from this tab; required bundled plugins stay visible with a disabled toggle.

Bundled and official plugins that register PluginSettingTabs or declarative configuration surface them here. Rows with plugin settings show a gear button next to the enable toggle, and clicking it opens the imperative tab when present or the matching declarative configuration section otherwise. The external official lapis-telemetry plugin exposes its browser telemetry settings from this section after install instead of relying on manual window.__LAPIS_TELEMETRY__ or localStorage edits.

Rows that expose inline panel content show a trailing chevron disclosure affordance, start collapsed, and expand a shared inline Details | Features tabbed panel on a full-width second row under the plugin name and action controls when the row is activated. The Details tab shows manifest summary metadata (version and author when present, plus description). The Features tab uses a natural-height two-column category/detail layout for runtime status, activation events, and any available privilege or capability details, leaving scrolling to the main settings pane instead of adding nested scrollbars. Core plugin rows intentionally omit version and author metadata, so those rows can show only the Details tab for description-only content or only the Features tab when feature metadata exists. Rows without details metadata or feature sections stay non-expandable and keep their visible summary metadata. Rerenders destroy and recreate the mounted Svelte instances so toggles and restart actions do not duplicate embedded panels.

The installed telemetry diagnostics plugin also registers Clear telemetry traces, which clears the live diagnostics buffer and any persisted vault-scoped IndexedDB copy.

Community Plugins Tab (community-plugins.ts)

Lists installed plugins with version/author. Toggle enable/disable, hotkeys, restart, and uninstall buttons. Plugins that register PluginSettingTabs or declarative configuration also show a gear button next to the enable toggle that jumps straight to the imperative tab or declarative configuration section.

Community plugin rows that expose inline panel content use the same trailing chevron disclosure affordance, start collapsed, and expand a shared inline Details | Features tabbed panel on a full-width second row under the plugin name and action controls. The Details tab shows manifest summary metadata (version, author, description). The Features tab uses the same natural-height two-column layout to group plugin state into Runtime Status, Activation Events, merged permission or capability pills, Commands, Configuration, Languages, Views, Services, and other indexed contribution buckets. Runtime Status starts with loader badges for ESM, CommonJS compatibility, hybrid fallback, Electron sidecar, fallback used, missing dependency, deprecated host API, and reload required, then lists selected host, module format, fallback entry, fallback-used status, reload policy, asset URL mode, version/hash URL, declared/scanned shared dependencies, undeclared or missing dependencies, deprecated host APIs, and private host APIs when those diagnostics exist. Empty sections are hidden, activation events and permissions render as monospace outline badges, command entries render as actionable item rows with trailing chevrons that execute through the app command registry, and trusted-desktop, loader, or invalid-contribution problems surface through inline alerts. Plugins that failed manifest preflight or module evaluation before registration still appear as indexed diagnostic rows with restart and disable actions, so unsupported runtime, capability, dependency, or contribution declarations remain understandable without editing files manually. Rows without details metadata or feature sections stay non-expandable and keep their visible summary metadata. Settings-search navigation reveals collapsed plugin rows before scrolling and highlighting them. Rerenders destroy and recreate the mounted Svelte instances so toggles and restart actions do not duplicate embedded panels.

Built-in Features (Core Plugins)

These features are loaded like plugins but live in the workspace package.

AppPlugin

Commands:

• app:new-note (⌘N) — Creates a new uniquely named markdown note at the vault root and opens it in the active leaf.
• app:import-local-vault — When the active vault uses OPFS, prompts for a local folder, copies its files into the current browser vault with overwrite semantics, reports copy progress through app.notifications, and keeps the reload action for applying imported .obsidian settings.
• app:open-vault — Clears the stored current vault profile and reloads the shell back to the vault chooser.
• app:restart-with-community-plugins-disabled — Restarts the current session in Safe Mode with community plugins disabled for the next boot only.
• app:restart-without-restoring-layout — Restarts the current session in Safe Mode and skips saved layout restoration for the next boot only.
• app:open-settings (⌘,) — Opens settings dialog.
• app:toggle-left-sidebar — Collapses/expands left sidebar.
• app:toggle-right-sidebar — Collapses/expands right sidebar.
• app:toggle-ribbon — Hides/shows ribbon (updates appearence.interface.showRibbon).
• app:split-down — Horizontal split of active leaf.
• app:split-right — Vertical split of active leaf.
• app:rebuild-vault-cache — Rebuilds metadata cache.

Registers VSCode icon pack (@iconify-json/vscode-icons).

FileExplorerPlugin

View type: "file:explorer".

The file explorer context menu includes a Copy Path submenu. Every file or folder can copy its vault-relative path, native desktop vaults can also copy the absolute system path, and files can copy an encoded lapis://open?vault=...&file=... URL. When the active host advertises native file-system actions, the same menu adds a separated desktop block for opening the selected item in the OS default app and revealing it in Finder, File Explorer, or the platform file manager. Browser/PWA sessions hide those native-only actions because OPFS and File System Access do not expose stable absolute paths or OS reveal/default-app hooks. On mobile-width viewports, app-owned file explorer menus use the shared drawer renderer instead of anchored context or popover menu surfaces.

Hierarchical folder tree with:

• Folder expand/collapse toggle.
• File open on click.
• Context menu: new file/folder, rename, delete, refresh.
• Rename and drag-drop move flows delegate through app.fileManager.renameFile() so note-link rewrites use the shared link formatter.
• Context menus are cached per visible path so active-file selection changes do not rebuild menu state for the whole tree.
• Create new file/folder with auto-naming (Untitled, Untitled 2, …) while selecting the new item in the explorer; newly created files also open in the active leaf.
• Explorer rows are rebuilt from the loaded vault entries rather than the vault’s nested child arrays so empty folders stay visible and duplicate child-path state during reloads does not break keyed rendering.
• Keyboard rename mode.
• Custom icon fetcher: maps file extensions to VSCode icons (vscode-icons:file-type-*).
• Special icons for .obsidian and plugin folders.
• Auto-reveal current file (configurable via file explorer toolbar and Workspace settings as workspace.fileExplorer.autoRevealCurrentFile; expands ancestor folders, scrolls the active file into view, and applies on load for the active file).
• Drag-drop reordering.

Commands: file-explorer:reveal-path, file-explorer:show-file-explorer.

TagsPlugin

View type: "tags".

Metadata-driven tag browser with:

• Counts derived from the current metadata cache, aggregated once per file.
• Search filtering and sort-order controls.
• Optional nested hierarchy display for slash-delimited tags.
• Expand-all and collapse-all control for nested tag trees, enabled only while hierarchy mode is active.
• Automatic refresh on metadata cache changed, deleted, and loaded events.

Commands: tags:show-tags.

WordCount Plugin

Registers editor extension via statusBarEditorPlugin. Updates status bar on editor changes (debounced 20 ms).

Calculations: Word count (Unicode-aware), character count, sentence count (.!? delimiters). Display: "{N} words" + "{M} characters". Click → menu with "X min read" (from editor.readingSpeed config).

LangCode Plugin

Registers TextFileView for non-markdown languages:

• javascript → .js
• typescript → .ts
• json → .json, .data
• text → .txt, .text
• yaml → .yaml, .yml
• css → .css, .scss, .less

Registers matching CodeMirror language extensions (javascript(), javascript({ typescript: true }), json(), yaml(), css()). The TypeScript view registers the browser TypeScript provider from @lapis-notes/language-service and mounts shared language-service completion, hover, diagnostics, and lint-gutter adapters for .ts files.

Hooks and State

drag-state.svelte.ts

Tracks drag operations: leaf, file, dropPosition, mousePosition. dragStart(event, leaf) creates a drag ghost element.

task-runner.svelte.ts

Sequential async task execution: addTask(name, executor, options?), start(). Reactive message property for progress display.

The shell currently wraps startup tasks in telemetry spans (app.boot, app.boot.task) so boot regressions can be attributed to the specific database, vault, plugin, layout, or metadata phase instead of only surfacing as a slow initial render.

watch-vault.svelte.ts

File system watcher. Listens to vault events (create, modify, delete, rename). Debounces with recentInternalEvents map (7.5 s TTL). Closes views for deleted files, updates references on rename, emits "file-change" for external changes.

watch-color-scheme.svelte.ts

Syncs appearence.baseColorSchema with userPrefersMode.current (mode-watcher).

watch-metadata.ts

Initializes app.metadataTypeManager.trackChanges() on mount.

watch.svelte.ts

Generic effect watcher: watch(getter, cb) calls cb(prev, current) on reactive changes.

useBoundingRect.svelte.ts

DOM measurement: useBoundingRect({resize?, scroll?, observe?}) → {ref, rect, update()}.

use-text-highlight.ts

Svelte action for highlighting query matches. It builds text nodes and <span class="suggestion-highlight"> nodes instead of assigning raw HTML, treats regex characters literally, and supports multi-word matching.

Configuration Schemas

Appearance (appearence.schema.json)

• appearence.baseColorSchema — enum: dark / light / system
• appearence.accentColor — color picker
• appearence.font.fontSize — 10–30px
• appearence.font.quickFontSizeAdjustment — boolean
• appearence.interface.showInlineTitle — boolean
• appearence.interface.showRibbon — boolean
• appearence.interface.showTabTitleBar — boolean
• appearence.advanced.zoomLevel — 10–30

Editor (editor.schema.json)

• editor.alwaysFocusNewTabs — boolean
• editor.defaultViewForNewTabs — enum: editing / reading
• editor.defaultEditingMode — enum: live-preview / source
• editor.readingSpeed — 100–600 wpm
• editor.display.* — readable line length, fold, line numbers, indents
• editor.behaviour.* — spellcheck, indent tabs, indent width

Workspace (workspace.schema.json)

• workspace.mobile.mode — enum (auto by default) choosing whether the renderer uses the mobile shell automatically, always, or never
• workspace.mobile.defaultPage — enum (editor by default) choosing whether the mobile shell opens on the active leaf or the tabs page
• workspace.mobile.showBottomNav — boolean (default true) controlling whether the mobile shell shows the floating dock
• workspace.mobile.includeSidebarsInTabs — boolean (default true) controlling whether the mobile tabs page lists left and right sidebar leaves
• workspace.mobile.includeFloatingInTabs — boolean (default true) controlling whether the mobile tabs page lists floating and popout leaves
• workspace.mobile.breakpointPx — number (default 768, clamped to 320..1280) defining the auto-mode viewport threshold
• workspace.editorAssociations — record map from VS Code-style glob patterns to editor-view IDs
• workspace.fileExplorer.autoRevealCurrentFile — boolean (default false); syncs between the file explorer toolbar and Workspace settings

Styling

CSS Architecture

app.css imports Tailwind, the shared @lapis-notes/ui/theme.css core theme layer, workspace custom CSS files, and bundled plugin source app.css entries from the monorepo. The workspace is the only full Tailwind app entry and does not import standalone plugin dist/styles.css assets for bundled plugins; published dist/app.css remains the package export for external consumers, while local workspace development stays on source CSS paths. External official plugins load packaged styles.css only after installation. The first-party artifact rules are documented in Plugin CSS Contract.

@lapis-notes/ui/theme.css owns the canonical palette, semantic aliases, and shared Obsidian compatibility helpers. Workspace-local workspace-shell.css owns the remaining app-specific shell variables and selectors for tabs, stacked tabs, ribbons, status chrome, hover state routing, placement-aware sidebar boundaries, tab border routing, and layout behavior, but it consumes the shared canvas, surface, text, border, neutral interaction, and accent tokens instead of acting as a separate palette source. Dark mode is the primary Obsidian-aligned target; light mode remains supported.

The effective style-system contract is documented in Style System.

The workspace currently pulls built plugin styles from sibling packages/plugins/*/dist/*.css outputs instead of package-exported CSS subpaths because the dev CSS pipeline does not consistently resolve linked workspace package exports. Search and Bases styling are imported from packages/plugins/plugin-search/dist/app.css and packages/plugins/plugin-bases/dist/app.css, not standalone CSS outputs. Shared palette and semantic theme variables live in @lapis-notes/ui/theme.css; workspace-local stylesheets like workspace-shell.css and codemirror.css consume those variables instead of redefining the palette.

Tailwind content sources:

• packages/api/src
• packages/ui/src
• packages/plugins/plugin-markdown/src
• packages/plugins/plugin-bases/src
• packages/plugins/plugin-search/src

Custom stylesheets: workspace-shell.css (workspace shell theming), codemirror.css (editor styling), codemirror-lint.css (workspace-owned lint chrome), app.css (app-specific).

Workspace shell BEM hooks

Workspace-owned renderer chrome exposes additive workspace-shell__* BEM classes in Svelte markup alongside existing Obsidian compatibility classes (workspace-tab-header, view-header, status-bar-item, and similar) and Tailwind utilities. Do not remove or rename the legacy classes when adding hooks; append the BEM classes in the same class attribute.

• Block: workspace-shell on the ready-state layout root in App.svelte
• Elements: workspace-shell__segment (double underscore), for example workspace-shell__status-bar-left
• Modifiers: workspace-shell__segment--modifier (double hyphen), for example workspace-shell__vault-chooser--loading

Existing CSS in workspace-shell.css and app.css continues to target Obsidian-style selectors. New theme, snippet, test, or host overrides should prefer the workspace-shell__* hooks.

Plugin Dependency Injection

Generated provider values from the host-module catalogue supply public CommonJS host modules in the plugin require() context:

• obsidian → @lapis-notes/api
• @codemirror/* → CodeMirror packages
• luxon — Date/time
• zod — Schema validation
• clsx — Class utility
• bits-ui — Headless components

deps.ts exports only explicit legacy/private compatibility overrides and browser fallbacks, including selected @lapis-notes/api/* and @lapis-notes/ui/* subpaths, historical Lucide icon subpaths, Svelte legacy/private subpaths, @lapis-notes/markdown, and browser-compatible crypto, url, and util shims.

Desktop Electron Package (@lapis-notes/desktop-electron)

The Electron desktop package is the first-party native desktop shell for Lapis Notes. It lives at packages/desktop-electron and mounts the shared renderer from @lapis-notes/workspace.

See ADR-003 for the decision rationale.

Responsibilities

packages/desktop-electron owns:

• Electron app lifecycle (main process, BrowserWindow creation, app events)
• Native window behaviour (title bar overlay, traffic-light positioning on macOS)
• Native drag affordances for tab/header regions that need to initiate window dragging from the shared workspace shell
• Native menus (File, Edit, View, Window plus debug entries)
• IPC command handlers for folder picking, revealing the selected vault root in the host file manager, vault-scoped file operations, scoped vault resource URLs, generated-state persistence, native file watching, native file actions, app URL launches, and native OS notification mirroring
• Native notebook DuckDB sidecar process management for Electron notebook query execution, timeouts, crash recovery, and app-table, virtual-file, and validated vault-file registration
• Native language-service Node sidecar (markdownlint + embedded TypeScript language service) routed through main-process IPC (desktop_ls_*) for renderer-backed LanguageServiceProvider registrations with bounded JSON payloads
• Desktop-only runtime adapters (NativeDesktopBridge registration), platform/capability metadata, and shell metrics that tune renderer titlebar spacing
• Package-local Vite config, TypeScript config, build/dev scripts, and Electron packaging metadata

Shared app behaviour remains in packages/workspace (renderer shell), packages/api (runtime kernel), and first-party plugins. Desktop-specific code belongs in this package only when it requires Electron main-process access.

Package Layout

Native IPC Commands

The Electron shell exposes this native command surface through the shared API bridge:

• desktop_pick_vault_folder — native folder-picker dialog (dialog.showOpenDialog)
• desktop_create_vault_folder — native create-or-pick dialog for Create New Vault; returns the selected folder after ensuring it exists
• desktop_open_demo_vault — resolves a stable Electron-owned userData/demo-workspace folder for the shared Open Demo Workspace chooser action and creates it on demand before the renderer seeds bundled fixture files into it
• desktop_move_vault_folder — native choose-destination flow for moving an existing vault folder; moves the folder and relocates the per-vault generated-state database to the new vaultId
• desktop_reveal_vault_folder — opens the active vault root in the host file manager so users can copy or back up canonical files outside the renderer
• desktop_fs_resolve_path — resolves a vault-relative file or folder path to an absolute host path for copy-path actions
• desktop_fs_to_vault_path — maps an absolute host path back to a vault-relative path when it is under the active vault root
• desktop_fs_open_path — opens a vault-relative file or folder through the OS default app
• desktop_fs_reveal_path — reveals a vault-relative file or folder in the host file manager
• desktop_fs_exists / desktop_fs_stat — path existence and stat queries
• desktop_fs_read_text / desktop_fs_read_binary — vault-scoped file reads
• desktop_fs_get_resource_url — returns a scoped lapis-vault-resource:// URL for read-only vault media and embeds
• desktop_plugin_assets_register — registers a verified installed plugin asset context for the active renderer window so the main process can serve lapis-plugin://[vault-id]/[plugin-id]/[version]/[sha256]/[path] module URLs without exposing arbitrary vault files
• desktop_fs_write_text / desktop_fs_write_binary — vault-scoped file writes
• desktop_fs_list — directory listing
• desktop_fs_mkdir / desktop_fs_rmdir / desktop_fs_remove — directory and file removal
• desktop_fs_copy / desktop_fs_rename — file copy and rename
• desktop_fs_watch_start / desktop_fs_watch_stop — host-native directory watching bridged into the shared vault watcher
• desktop_db_load_state / desktop_db_save_state — native SQLite-backed generated-state persistence outside the vault; load probes return null without creating a SQLite file when neither SQLite nor legacy JSON state exists
• desktop_vault_bootstrap_kv_get / desktop_vault_bootstrap_kv_set / desktop_vault_bootstrap_kv_set_many / desktop_vault_bootstrap_kv_get_many / desktop_vault_bootstrap_kv_del / desktop_vault_bootstrap_kv_keys / desktop_vault_bootstrap_kv_is_empty / desktop_vault_bootstrap_kv_import_if_empty — main-process JSON persistence for vault profile pointers, saved recent profiles, and desktop-global bootstrap settings such as chooser appearance so startup does not depend on renderer IndexedDB when the Chromium profile misbehaves
• desktop_notifications_show — validates and mirrors selected durable app notifications through Electron’s OS notification API
• desktop_ls_capabilities — returns { markdown, typescript } feature flags once the preload protocolVersion matches Electron main expectations (no sidecar spawn)
• desktop_ls_update_document — pushes a sanitized VirtualDocument plus globals into the forked Node sidecar (document priming parity with worker document/update)
• desktop_ls_diagnostics — returns diagnostics arrays for Markdown (markdownlint) or TypeScript/JavaScript (embedded LS)
• desktop_ls_completions / desktop_ls_hover / desktop_ls_definition — position-based intelligence for TS/JS hosts
• desktop_ls_code_actions — presently returns []; reserved while browser workers also return empty payloads

All file operations are scoped to the selected vault root. .., root, and absolute-subpath escape attempts are rejected. The resource URL command uses the same path validation and serves files through an Electron-registered lapis-vault-resource:// protocol instead of exposing arbitrary raw file:// paths to renderer-owned media views.

The desktop package registers lapis:// and the compatibility lapis-notes:// scheme with the OS. URLs received during cold start, macOS open-url, or Windows/Linux second-instance launches are queued in the main process until the renderer has mounted and can dispatch them through app.urls. The first supported action is open, including vault/file, desktop path, shorthand vault URLs, and pane-type hints where the shared workspace supports them.

Bootstrap Sequence

1. Electron main process creates BrowserWindow with contextIsolation: true, nodeIntegration: false, and the context-isolated preload script.
2. Preload exposes window.__LAPIS_NATIVE_DESKTOP__ with the IPC command stubs, native platform details, capability registry, and shell metrics via contextBridge.exposeInMainWorld.
3. Renderer entry (src/main.ts) reads the preload bridge, applies shell-owned CSS metrics such as the macOS leading safe-area inset, calls setNativeDesktopBridge(bridge) on the shared API runtime, migrates any legacy vault profile keys from renderer IndexedDB into a main-process JSON store when that store is still empty, registers that main-process store via setDefaultVaultStateStore, and calls mountWorkspaceApp(). Before mounting the shared workspace shell, the renderer also reads the desktop-global bootstrap appearance setting from that same store and applies the matching light/dark document classes so the chooser can render in the expected theme before vault configuration becomes available.
4. VaultBootstrap.svelte detects the native bridge and routes to the desktop-folder vault selection flow.
5. VaultSession resolves to NativeDesktopAppDatabase, which persists the serializable AppDatabase state shape in a per-vault SQLite file under Electron app.getPath('userData') outside the selected vault folder. Metadata cache snapshots are additionally mirrored to .lapis/cache/metadata-cache.json as rebuildable vault-local generated state so copied/imported vaults can hydrate the app database when the host-owned SQLite file is absent.

Vault profile records (last-opened vault / saved profiles) persist under app.getPath('userData')/vault-bootstrap-kv.json in the Electron main process. The same file now also carries desktop-global chooser settings such as the bootstrap appearance mode. The renderer runs a best-effort, time-bounded migration from the legacy IndexedDB store (lapis-notes-vault-state) only while that file is still empty, so Chromium storage or service-worker database errors in the renderer profile are less likely to strand the shell on the “Opening vault” bootstrap screen.

The shared chooser now presents a desktop-first landing page on Electron: branded header, Create New Vault, Open Demo Workspace, Open Vault, inline recent projects, command-style recent-project search, and a settings link that edits only bootstrap-relevant appearance state. Create New Vault uses desktop_create_vault_folder, Open Demo Workspace uses desktop_open_demo_vault to resolve a stable Electron-owned demo folder before the shared renderer seeds its bundled fixture files, and Open Vault continues to use desktop_pick_vault_folder. On a first launch with no saved or recoverable vaults, the shared chooser defaults to the same create-first landing used by the browser host, promoting Create New Vault and switching the hero copy to Create a vault; once recent vaults exist it returns to the normal Open a vault landing. Recent projects remain the saved vault-profile records in the bootstrap KV store, ordered by most recent updatedAt. Inline recent-project rows now expose actions for copying the saved vault id, renaming the stored vault alias used by app.urls, revealing the vault root, removing the saved profile, and moving the vault folder. The move flow updates the saved profile root path and migrates Electron’s host-owned generated-state files from the old path-derived vaultId to the new one so search and app state continue to follow the moved vault.

Because Electron mounts the shared workspace bootstrap with the browser popout host enabled, openPopoutLeaf(), moveLeafToPopout(), and paneType=window requests now open a real secondary Electron popup window rather than falling back to an in-window floating pane. Electron main applies the same BrowserWindow shell policy to those window.open('about:blank') popouts that it uses for the initial app window, so secondary windows inherit the same hidden macOS title bar, preload bridge, and shell metrics before the shared workspace renderer mirrors document classes plus stylesheet and plugin CSS changes into the popup document, mounts the same recursive WorkspaceWindow -> TabsSplit shell there, and removes the popout from persisted layout state when the popup closes. The popout window itself does not mount a second top-level App; the owning app-host window keeps the live runtime, tracks focused popout state inside app.workspace, and receives native menu-open-vault events plus queued lapis:// app URLs on behalf of the focused popout.

The Electron native app database also mirrors prepared search documents into the same per-vault SQLite store and uses FTS5 for candidate selection on plain lexical searches. desktop_db_load_state checks for an existing SQLite file before opening the database so probing for missing generated state does not leave an empty vault-state/<vaultId>.sqlite3 file behind. If only legacy JSON state exists, load returns that JSON and migration waits until a later save. When a platform-compatible sqlite-vec extension is available, ready chunk embeddings are mirrored into a native vec0 table and vector/hybrid searches use that table for candidate selection before the shared evaluator builds final results. If sqlite-vec cannot be loaded or dimensions do not match, vector and hybrid searches fall back to the shared in-memory vector scorer over the mirrored documents.

The Electron notebook capability is available through a native DuckDB sidecar. Electron main forks a Node child process backed by @duckdb/node-api, routes notebook query and registration requests over IPC, enforces a 30-second request timeout, kills and restarts the sidecar after crashes or timeouts, and shuts it down during app quit. The sidecar keeps its own temporary working directory for registered DuckDB file aliases so existing notebook SQL such as read_csv_auto('alias') continues to work without syntax changes. Vault-backed CSV, Parquet, and JSON registrations pass the resolved notebook path and active native vault root to Electron main, which validates the path under the selected vault before the sidecar links or copies the file into that working directory. The notebook plugin injects this provider only when the preload capability registry advertises notebook as available; browser/PWA notebooks continue to use DuckDB-Wasm and byte-buffer registration.

The Electron plugin-sidecar capability is available as electron-plugin-sidecar with the desktop_plugin_host_* protocol family and an Electron-main-owned child-process boundary. Electron main now owns a trusted per-plugin sidecar keyed by vault/window context plus plugin ID, so crashes, timeouts, restart budgets, and cooldown failures are isolated per hosted plugin instead of shared across every trusted desktop plugin in the window. Each sidecar can prepare, evaluate bundled-only CommonJS Lapis desktop entries, activate/deactivate them, and route the initial parent-brokered capability set for vault I/O, plugin data, commands, notices, settings snapshots, metadata snapshots, event subscriptions, and logging. The sidecar CommonJS v1 resolver exposes only lapis and @lapis-notes/api from the generated host-module catalogue; local require() calls fail with a bundle-required diagnostic, and renderer-only dependencies such as obsidian, Svelte, DOM/CodeMirror view modules, and @lapis-notes/ui fail with explicit unsupported-sidecar dependency messages. The shared API runtime selects this host only for desktop/sidecar-aware community plugins or plugins that request brokered capabilities; baseline renderer-compatible community plugins continue through the renderer execution host. The durable design is documented in Community Plugin Host Boundary.

The Electron plugin-asset capability is available through preload as plugin-assets with provider electron-plugin-protocol. Renderer bootstrap installs a PluginAssetServer for native vault sessions; it reads verified installed-plugin metadata from the active vault, verifies the requested entry file once through the shared adapter path, registers the plugin/version context through desktop_plugin_assets_register, and returns a version/hash lapis-plugin:// URL. Electron main registers lapis-plugin before app readiness, tracks registered contexts by owning window, rejects unregistered vault/plugin/version/hash/path requests, and verifies the URL hash segment, file size, and SHA-256 against installed metadata before returning a JavaScript, CSS, JSON, WASM, or image response. Window cleanup removes owned plugin-asset contexts so the protocol cannot outlive the renderer vault session that registered it.

The Electron notifications capability is available through preload as electron-notification. The required notifications plugin still listens to app.notifications in the renderer, but only mirrors records that were persisted into generated app state. Preload forwards those payloads over desktop_notifications_show; Electron main validates the bounded payload, suppresses duplicate IDs for the window session, and calls Electron’s native Notification API when the host supports OS notifications.

The Electron language-service capability advertises language-service in the preload capability registry as electron-language-service-sidecar. Electron main forks a Node child modeled on the DuckDB manager (30-second request timeouts, restart after crashes/timeouts, shutdown on quit) and validates every payload for protocol version mismatches plus bounded document/global text lengths before forwarding work. Renderer entry (desktop-electron/src/main.ts) now registers only the native TypeScript provider during host bootstrap; the external official Markdown Lint plugin consumes the same desktop_ls_* capability through the shared native bridge and registers native markdownlint itself when installed and enabled, so markdown diagnostics ownership stays with a first-party official plugin rather than with the host bootstrap path. Browser worker providers remain registered as fallback parity, and LanguageServiceManager continues to merge diagnostics/code actions only among the highest priority tier while completions, hover, and definition already stop at the first successful provider sorted by descending priority.

Read-only vault resources requested through Vault.getResourceUrl() are delegated from preload to the main process, which returns cache-busted lapis-vault-resource:// URLs. Markdown image views, PDF views and embeds, and Bases card images consume that URL path so Electron avoids renderer-side full-file blob copies for those assets while the browser adapters keep their blob URL fallback.

When the bridge advertises native watch support, NativeDesktopVaultAdapter forwards watch requests through preload to Electron main-process chokidar watchers so the workspace can react to external file changes without falling back to polling.

The shared workspace shell uses data-desktop-drag-region markers on non-interactive chrome. In Electron, native window dragging comes from real -webkit-app-region drag surfaces on the non-interactive header regions such as tab spacers and the page-title header container, while interactive descendants stay opt-out no-drag regions so clicks, renames, and tab drag/drop keep working.

Dev and Build

# Start the Electron dev host (renderer Vite + Electron main)
pnpm dev:desktop
# or from the package
pnpm --filter @lapis-notes/desktop-electron dev

# Build the renderer bundle (also builds bundled workspace plugin dist outputs first)
pnpm --filter @lapis-notes/desktop-electron build

# Run checks
pnpm --filter @lapis-notes/desktop-electron check

# Validate the packaged app layout
pnpm --filter @lapis-notes/desktop-electron package:dir

# Build release artifacts
pnpm --filter @lapis-notes/desktop-electron dist:mac:all
pnpm --filter @lapis-notes/desktop-electron dist:linux

# Verify, build, tag, and upload a local desktop release (set FORGEJO_TOKEN in .env or export it)
pnpm release:desktop:local -- --version <version-without-v> --targets all

Dev port: 1421 (distinct from the workspace dev port 5173).

pnpm dev:desktop and pnpm --filter @lapis-notes/desktop-electron dev must always load the renderer from the live Vite source server via LAPIS_DESKTOP_DEV_SERVER_URL. The root Turbo dev task explicitly passes through LAPIS_DESKTOP_* variables so test-vault, user-data, devtools, and diagnostic launch controls reach the package dev launcher. The Electron dev host must not fall back to dist/index.html when running those dev flows, and the dev launcher strips inherited ELECTRON_RUN_AS_NODE before spawning Electron so package-manager or test environments cannot accidentally run the desktop main process as plain Node. Unless LAPIS_DESKTOP_USER_DATA_DIR is set explicitly, the dev launcher assigns a repo-scoped temporary user-data directory so a packaged Lapis Notes app running on the same machine cannot steal the single-instance lock or receive the dev launch as a second-instance event. In dev-server mode, closing the last Electron window quits the app even on macOS so the dev shell can shut down Vite and TypeScript watchers cleanly.

Packaged Electron builds use the in-package build/icon.png, a rounded-square app tile derived from the shared workspace branding asset at packages/workspace/src/assets/lapis.png, so the desktop shell ships an icon that reads like a native app icon instead of a floating transparent mark. Before package:dir / dist:* invoke Electron Builder, scripts/generate-build-icons.mjs regenerates build/icon.png, build/icon-light.png, build/icon-dark.png, and macOS build/icon.icns (on macOS) so x64/arm64 packaging does not fall back to the default Electron icon when generated build resources are missing. On macOS, Electron main also switches the running app dock icon between build/icon-light.png and build/icon-dark.png based on the current system appearance during both packaged runs and pnpm dev:desktop, while build/icon.png remains the packaged bundle fallback. The package metadata now also declares productName: "Lapis Notes", and Electron main still calls app.setName("Lapis Notes") at startup, so dev, e2e, and unpackaged runs use the branded menu and dock label instead of the default Electron binary name.

Electron main now also owns a small native app-info surface for branding and diagnostics. The shared renderer About Lapis Notes command calls desktop_app_info_get to read the desktop app version and build timestamp when the native bridge is available, while Electron’s native About panel is configured through app.setAboutPanelOptions() with the same name, version, icon, and a credits line that shows the build timestamp when the packaged or built bundle exposes one.

Release artifact names are stable and hyphenated for Forgejo downloads and Homebrew tap updates:

• Lapis-Notes-<version>-mac-arm64.dmg
• Lapis-Notes-<version>-mac-x64.dmg
• Lapis-Notes-<version>-mac-arm64.zip
• Lapis-Notes-<version>-mac-x64.zip
• Lapis-Notes-<version>-linux-x64.tar.gz
• Lapis-Notes-<version>-linux-x64.AppImage

pnpm release:desktop:local -- --version <version> --targets all is the local release path for a macOS developer machine. It checks that the input version matches packages/desktop-electron/package.json, refuses to release from a dirty JJ working copy unless --allow-dirty is passed, runs the repo checks plus smoke tests by default, builds macOS and Linux artifacts, writes SHA256SUMS.txt, and uses the Forgejo API to create/update v<version> plus release assets. On non-macOS machines, --targets current resolves to Linux and macOS targets are rejected.

The Forgejo desktop release workflow builds Linux desktop assets on ubuntu-latest, builds macOS arm64/x64 DMG and ZIP assets on macos-arm64, combines checksums, and publishes one release containing every desktop asset. The local macOS command remains available for developer-run releases and dry-runs.

The Electron Builder package scripts pass --publish never and set CI=1 plus ELECTRON_BUILDER_DISABLE_UPDATE_CHECK=true; Forgejo tag creation, release creation, checksums, and uploads are handled by repo release scripts rather than Electron Builder’s publishing integration or update checks.

During development, renderer source changes reload through Vite, while src-electron main/preload changes trigger a TypeScript watch rebuild followed by an Electron process restart.

Validation

• pnpm --filter @lapis-notes/api build
• pnpm --filter @lapis-notes/desktop-electron check
• pnpm --filter @lapis-notes/desktop-electron build
• pnpm --filter @lapis-notes/desktop-electron test:e2e:smoke (local dev renderer; CI uses full build)
• pnpm --filter @lapis-notes/desktop-electron dist:linux
• pnpm --filter @lapis-notes/desktop-electron dist:mac:all on macOS release machines
• pnpm release:desktop:local -- --version <version-without-v> --targets all --skip-upload for local release dry-runs (FORGEJO_TOKEN in .env or exported)
• pnpm --filter @lapis-notes/desktop-electron exec playwright test -c ./playwright.config.ts e2e/grouped-sidebar.spec.ts
• pnpm --filter @lapis-notes/desktop-electron exec playwright test -c ./playwright.config.ts e2e/language-service-markdown.spec.ts
• pnpm --filter @lapis-notes/desktop-electron package:dir
• pnpm --filter @lapis-notes/workspace exec playwright test e2e/workspace-shell-visual.spec.ts -g "electron macOS sidebar header subtracts the ribbon width from the traffic-light inset"
• Manual smoke against ~/Documents/vault-copy

Open Design Items

The Electron community-plugin host boundary is now designed in Community Plugin Host Boundary. Remaining implementation slices are documented on the owning package and contract pages.

Plugin Packages

Plugins are a first-class architectural unit. They provide both bundled product features and community-style extensions.

Package Groups

First-Party Plugins

Canvas, Graph, Markdown Lint, Notebook, PDF, Slides, Telemetry, and Docs are external official plugins. Their packages remain in the monorepo for building and publishing official artifacts, but the workspace does not register them in the bundled core list. Installed official records with provenance: "official" still appear under Core plugins and activate through optional-core Safe Mode policy. Bases remains bundled and non-installable for this phase.

Obsidian-Targeted Packages

The spellchecker package keeps its own permissive package metadata because it is an Obsidian-targeted compatibility package rather than a bundled Lapis core plugin in the current app boot sequence.

Styling Ownership

First-party plugin UI should follow the shared Plugin CSS Contract. The contract owns the current CSS artifact rules and rollout tracker so individual plugin pages can describe package-specific selectors without duplicating global policy.

Workspace-Local Built-in Features

The workspace package also contains features that behave like plugins but are not distributed as separate packages:

These are documented in detail on the Workspace App page.

Community Plugin Loading

Plugin Runtime owns the common runtime contract for bundled and community plugins. The workspace shell now creates a CommonJS dependency resolver from generated host-module metadata and generated provider values, while deps.ts is limited to explicit legacy/private overrides and browser fallbacks, so plugins can still require() common packages such as obsidian, selected @lapis-notes/api/* exports, @codemirror/*, luxon, zod, clsx, and bits-ui.

This allows community plugins written for the Obsidian API to run with minimal or no modification when the active host supports the required APIs.

Architecture Patterns

Markdown Plugin (@lapis-notes/markdown)

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

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

The markdown package is the primary document-editing plugin. It owns Markdown language support, media viewing, outline/property side views, markdown preview rendering, metadata extraction, and most CodeMirror extensions used by note editing. Metadata-driven markdown surfaces are expected to scope cache reactions to the active note or its direct reference neighborhood rather than treating every metadata event as a full-view refresh trigger. Markdown preview surfaces that receive shared Editor instances are expected to scope change subscriptions to the specific editor instance they mounted so embed/file swaps can tear down safely even after the live prop is cleared.

Non-image file embeds route through the app embed registry so other plugins can supply plugin-owned inline viewers without widening shared preview sanitization rules. The rehype embed component resolves short embed paths against the active source note through MetadataCache, so embeds render from either full vault paths or the same shortest-path link text used elsewhere, and it re-resolves mounted embeds when metadata finishes loading, when the source note changes, and when the directly resolved embed target changes or disappears. Vault create, delete, and rename events remain the fallback path for new shortest-path resolutions that do not have enough metadata context yet. Image media views consume Vault.getResourceUrl() and revoke URLs on teardown, which lets Electron use the scoped native resource protocol while browser vaults keep blob URL fallback behavior. In the rich editor, standalone ![[...]] paragraphs mount through the same markdown block-widget renderer path, so live preview uses the same file-embed surface as reading mode for PDF and other non-image embeds. That registry path now also carries first-party read-only Bases and Canvas file embeds for .base/.bases and .canvas targets. The package also exports a reusable read-only FileEmbed surface so other plugin UIs can reuse the same image, section, custom-embed, and text fallback behavior outside markdown documents.

The package now also exports narrow embed surfaces through @lapis-notes/markdown/embed: read-only MarkdownEmbed, editable EditableMarkdownPreview, and read-only FileEmbed. Official external plugins use that subpath when they need markdown surfaces without importing the full markdown plugin root graph. MarkdownEmbed accepts plain markdown text plus optional source-path and plugin-extension hooks, and renders preview output without requiring an Editor instance, plugin lifecycle, or app-owned directive/postprocessor registries. The first embed slice intentionally excludes app-resolved file embeds, custom directive registration through app.markdownDirectiveRenderers, and markdown postprocessor execution.

Markdown style ownership is split by surface. Shared variables and rendered markdown rules live separately from source-mode, live-preview, reading-mode, and embedded-mode overrides under src/styles/. The stable mode hooks are markdown-source-mode / markdown-source-view, markdown-live-preview-mode / markdown-live-preview-view, markdown-reading-view, and markdown-preview-surface--embedded / markdown-embed-surface, so CSS selectors can target one surface without relying on broad global markdown selectors or :not(.cm-live-preview) fallbacks.

Top-tab-specific markdown CSS hides markdown view icons only for top tabs, while leaving stacked and other tab header variants to display their icons.

The tracked e2e-vault/plugin-markdown/CodeMirror Layout Showcase.md fixture is the focused manual and automated sample for CodeMirror layout behavior. It covers GFM tables, grid tables with inline markdown, blockquotes, quoted lists and checklists, nested list indentation, continuation paragraphs, line wrapping, embeds, internal links, tags, math, fenced code, and Mermaid across source mode, live preview, and reading mode.

Inline Mermaid blocks render as scroll-friendly static SVG previews in reading mode and live preview, while the Mermaid expand dialog owns the interactive svg-pan-zoom controls for large diagrams.

Registered Views

Public Embeds

• @lapis-notes/markdown/embed exposes MarkdownEmbed, EditableMarkdownPreview, and FileEmbed for markdown preview surfaces that official external plugins can bundle without importing the full markdown plugin root graph.
• @lapis-notes/markdown continues to expose MarkdownPreview, EditableMarkdownPreview, FileEmbed, and NoteLink for richer plugin-integrated use cases. MarkdownPreview accepts frontmatterOpen (default true); FileEmbed forwards frontmatterOpen (default false) so note-link hover previews and inline embeds start with the Properties block collapsed while reading mode and live preview remain expanded.

Commands

• show-all-properties
• show-outline
• show-file-properties
• show-backlinks
• show-outgoing-links
• show-links-sidebar

Link Sidebars

Markdown owns Obsidian-inspired Backlinks and Outgoing Links side views. Both register as sidebar views on the right side under the grouped sidebar tab named Links with Backlinks above Outgoing links. The plugin seeds that group only when the right sidebar has no saved children; existing non-empty user layouts are preserved until a command explicitly opens a view.

The Backlinks view follows the active markdown note. Its Linked mentions section groups cached links and embeds from other markdown notes that resolve to the active file. Its Unlinked mentions section searches indexed markdown document content for exact active-note basename and alias matches, excludes matches already inside link/embed ranges, skips frontmatter, and falls back to vault reads for files that are not yet present in the generated search index.

The Outgoing Links view follows the same active markdown note. Its Links section lists resolved internal links and embeds from the active note grouped by target file. Its Unlinked mentions section scans the active note for exact basename and alias matches for markdown files that are not already linked by that note.

Both sidebars use the same compact sidebar result language as All Properties and Search: fixed icon toolbar, optional search panel, collapsible section titles, collapsible result groups, search filtering, context expansion, sort menu, and scrollable rows. Result rows open files in the main workspace area; backlink rows jump to the source mention. Hovering a result uses the shared Hover Card plus FileEmbed preview surface, previewing the backlink source note or outgoing target note.

Editor Ownership

The package extends CodeMirror with markdown table editing, heading/list decorations, grid tables, wiki links, tags, embeds, directives, LaTeX, paste handlers, completion, rich-editor behavior, local path-link parsing for standard markdown destinations that contain raw spaces, and a markdown-owned frontmatter line-decoration pass that marks every YAML frontmatter source line with cm-hmd-frontmatter, including both delimiter lines, so the editor can style the full block consistently. Standard live-preview markdown tables now mount @dnd-kit/svelte row drag handles and drop targets inside the rich-editor widget surface, so row reordering no longer depends on the older native HTML5 drag path. Shared autocomplete defaults and tooltip alignment come from the API lapisCodeMirrorAutocomplete() helper and @lapis-notes/ui/codemirror-autocomplete.css; markdown supplies override completion sources (wiki links, suggestions) and markdown-only addToOptions renderers. Vault file scanning for link completions uses API helpers (vaultFilesMatchingPathSubstring, embed filters). Completion-driven note, embed, heading, and display-text link insertion delegates to the shared API internal-link formatter so link text resolves relative to the active note and uses the same shortest-path rules as metadata and file-management helpers. Its custom language extends the Markdown Lezer parser with GridTable, Table, WikiLink, path-link, Tag, directive nodes, YAML frontmatter, and fold support, while keeping wiki-link and embed parsing line-local so malformed cross-line link text does not create invalid rich-editor replacement ranges and recovering embed tokens when a literal exclamation mark directly precedes ![[...]]. Both the standard editor link-decoration pass and the rich-editor pass apply the same internal-link, target, and display-text classes to embed nodes that they already apply to wikilinks.

The plugin mounts the shared CodeMirror diagnostics/lint-gutter adapters for MarkdownViewType, while the external official Markdown Lint plugin owns markdown diagnostics provider registration when installed and enabled. Markdown diagnostics remain single-document only and do not depend on metadata cache, vault-wide link resolution, or markdown preview rendering.

Markdown-owned list, plain-indent, and blockquote editor decorations emit first-paint hanging-indent fallback variables, and the measured-indent pass later writes measured pixel variables over the same CSS contract. Source and live-preview wrapping therefore keep continuation rows aligned during opening, scrolling, and caret movement into raw prefixes instead of waiting for a post-layout style replacement. Unordered-list marker spacing is expressed through shared marker-slot custom properties, so list fallbacks, anchored continuation padding, and indentation-guide offsets account for the same visual bullet width across source mode and live preview.

Markdown fenced code blocks continue to dispatch through the shared per-language code-block processor registry. The bundled Bases plugin now uses that path for fenced base and bases blocks, rendering the fence body as a read-only Bases document in reading mode and live preview without adding new markdown syntax.

List Callouts

The markdown plugin owns inline list callout markers (for example - & Highlighted item) in source, live preview, and reading mode.

Default callout characters: & (yellow), ? (orange), ! (red), ~ (purple), @ (cyan, book-open icon), $ (green), % (gray). Users can add custom callouts from the Markdown plugin settings tab, whose catalog editor uses the shared icon picker for icon-backed callouts and keeps preview rows with representative sample text.

Settings:

• Callout catalog persists in /.obsidian/markdown.json under listCallouts.
• Appearance (background opacity and padding) persists as the canonical object setting markdown.listCallouts.style in app.json. Runtime style access still reads child values through markdown.listCallouts.style.*, and those values map to --lc-* CSS variables on markdown surfaces.
• Legacy flat app.json keys such as markdown.listCallouts.style.paddingLeft are normalized into markdown.listCallouts.style when no object value exists and are pruned after normalization. If both forms exist, the object value wins.
• Legacy obsidian-list-callouts community plugin data is imported once into markdown.json when no catalog is present yet.

Blockquote Callouts

The markdown plugin also owns Obsidian-style blockquote callouts (for example > [!warning] Title) in reading mode and live-preview block widgets.

The blockquote callout transform runs after markdown parsing and must recognize both raw [!type] text prefixes and the bracket-only internal-link tokens produced by the markdown path-link extension. Rendered callouts use the markdown plugin’s callout component plus shared callout theme variables, so reading mode and live-preview widgets share the same callout DOM shape and styling.

Metadata Ownership

Markdown metadata extraction is worker-backed through PromiseWorker. The plugin registers the metadata processor for .md files and provides the frontmatter/property widgets used by the workspace and related plugins. Package build emits dist/lib/metadata/worker.js after svelte-package so downstream plugin builds can load the worker through import.meta.url instead of unresolved Vite ?worker&inline imports.

The shared frontmatter editor now uses a Svelte-owned property-name input with anchored suggestions in both live preview and the File Properties side view instead of the older imperative menu-attached blur flow. Property rows are keyed by exact nested frontmatter paths, so rename and type-menu actions now target the concrete property path that exists in a note rather than only the top-level key. Normal row rendering depends on the active note frontmatter, persisted type declarations, registered widgets, and local inference rather than vault-wide observed property counts, while property-name suggestions load the vault-wide property list lazily when an input is focused. Note-local property edits in live preview and the File Properties side view now share the same helper around FileManager.processFrontMatter(), which lets first-property adds create a new YAML block, last-property removals drop the whole block, and widget edits preserve concurrent note changes. Built-in widgets now commit text values on input/blur/Enter and checkbox/date/number changes on stable change/blur events so remounts and focus handoffs do not lose pending edits. Embed-hosted previews (FileEmbed, including note-link hovers and inline ![[embeds]]) collapse the Properties block by default; reading mode and live preview keep it expanded unless a host overrides frontmatterOpen.

The All Properties side view is a top-level frontmatter key browser. It builds rows from exact keys present in cached YAML objects, preserving literal dotted keys such as note.status while hiding generated nested paths such as tags[0] or prop[0].name from the root list. Object and complex-array rows can expand into an indented nested-property tree. Object rows show concrete generated child paths with counts and the same rename, type-change, and delete actions using nested path semantics. Complex arrays aggregate object-child paths across indexes, so items[0].name and items[1].name render as a single name/items[].name style child instead of separate numeric index rows. Clicking any property row opens the Search sidebar with a quoted property query; aggregate array child rows normalize items[].name to the searchable nested filter ["items.name"]. Each top-level row also exposes bulk Rename, Change Property Type, and Delete Property actions; those actions operate across affected files through exact top-level YAML keys, report progress through the shared notifications status item, and summarize partial failures.

The frontmatter widgets include generic removable pill rendering for tags, aliases, and primitive multi-text arrays. Editable list pills do not force markdown tag prefixes in the Properties editor, autocomplete new values from existing metadata values for the same property, and render whole wikilink values through NoteLink with hover preview and click-to-open behavior resolved from the active note path.

Rendered markdown preview and reading-mode surfaces apply the same markdown heading tokens used by the editor so heading color, size, weight, and font variables stay consistent across modes. Markdown-specific callouts and table-selection styling inherit shared theme-owned compatibility tokens rather than maintaining plugin-local light/dark palette blocks. The shared editor wrapper and Outline side view also cancel deferred focus and heading-observer work on teardown so preview/editor transitions and leaf changes do not leave stale async UI work running. The Outline side view initializes nested heading groups expanded whenever the active note changes, then preserves user collapse choices for that note.

Rendered note-link hover previews and unresolved-link tooltips inherit their popup ownership from the shared Hover Card and Tooltip primitives. Popup-hosted reading views therefore keep note-link overlays inside the popup document without markdown-specific portal props at the call site.

Related Contracts

• Editor Rendering and Views
• Storage, Metadata, and Search
• Plugin Runtime
• Plugin CSS Contract

Markdown Lint Plugin (@lapis-notes/markdown-lint)

Source: packages/plugins/plugin-markdown-lint/src/

Package: @lapis-notes/markdown-lint. Manifest id: lapis-markdown-lint.

The Markdown Lint plugin is an external official plugin that owns markdown diagnostics provider registration. It separates markdownlint ownership from the main Markdown editing plugin while preserving the existing editor diagnostics UI and host fallback behavior.

The plugin now also owns vault-scoped markdownlint rule suppression settings, per-diagnostic ignore actions, and markdownlint quick-fix surfacing for fixable diagnostics.

Registration

• Official registry install under /.obsidian/plugins/lapis-markdown-lint.
• Listed under Core plugins when installed provenance is official, with enablement persisted through the existing external plugin enablement file.
• Declarative manifest language-service contribution with one provider binding.
• Declarative manifest-only configuration contribution for vault-scoped markdown-lint settings.
• Registered as an optional external official plugin, so optional-core Safe Mode disables it while community-plugin Safe Mode does not.
• No views, commands, or bespoke settings tabs.
• Exports a concrete MarkdownLintPlugin subclass and registers exactly one Markdown LanguageServiceProvider during plugin onload().

Provider Selection

• On browser/PWA hosts, the plugin registers the worker-backed markdownlint provider from @lapis-notes/language-service, whose worker bundles markdownlint runtime entry points for browser module resolution.
• On Electron hosts where the native language-service capability is available and responsive, the plugin registers a native markdownlint provider that talks to desktop_ls_* IPC through the shared native desktop bridge.
• The provider keeps priority: 100 on Electron so native markdownlint outranks the browser worker while preserving worker fallback when the native capability is unavailable.
• Both runtime paths expose markdown diagnostics and markdown code actions for fixable markdownlint rules.

Settings

• The plugin contributes a vault-scoped markdown-lint.disabledRules array in app configuration.
• Each configured rule ID is mapped to false in the effective markdownlint config for both worker and native providers.
• Inline markdownlint suppression comments continue to work because the underlying markdownlint library still evaluates them during linting.

The first implementation deliberately limits persisted settings to rule suppression. Full markdownlint rule-option passthrough and external config-file loading remain out of scope.

Quick Fixes And Ignores

Markdownlint diagnostics with rule ids expose three code actions through the shared Lapis lint tooltip:

• Fix markdownlint <RULE>
• Ignore markdownlint <RULE> on next line
• Ignore markdownlint <RULE> for this file

Ignore-next-line inserts a markdownlint-disable-next-line HTML comment immediately before the offending content line, but it is not offered for diagnostics inside leading YAML frontmatter because HTML comments are not valid frontmatter content. File-level ignores insert markdownlint-disable-file before the first real content line, after any leading YAML frontmatter, and include MD041 when needed so the inserted comment does not create a new first-line-heading warning.

Lapis MD018 replacement

In-app lint disables stock markdownlint MD018 and registers a Lapis custom replacement through @lapis-notes/language-service (createMarkdownlintLintOptions()).

The replacement registers as MD018-lapis in markdownlint because built-in rule names cannot be reused, but diagnostics surface as MD018 so vault disabledRules, inline markdownlint-disable MD018 comments, and editor doc links continue to work.

Tag-aware behavior:

• Exempt whole-line lowercase Lapis tags such as #task, #project/roadmap, and indented tags with up to three leading spaces.
• Exempt line-start tag prefixes such as #task Buy milk.
• Do not report valid spaced ATX headings such as # Intro, ## Start Here, and ### Deep Dive.
• Still report malformed ATX headings such as #Introduction, ##Section, ###foo, and #Heading.
• Preserve the quick-fix that inserts a space after the hash run for remaining violations.

Tag exemption matches Lapis inline tag conventions: optional up-to-three-space indent, single #, lowercase letter first, then lowercase letters, digits, _, -, and /.

Both the browser worker and Electron sidecar use the same shared lint options helper so behavior stays aligned across hosts. They also share the same markdownlint runtime helper for diagnostic mapping, code-action generation, inline suppression alias normalization, and applyFixes(...)-based edit generation so fixes preserve frontmatter and edit the real violation line instead of rewriting from the top of the file.

Package Boundary

• Owns markdown diagnostics provider registration only.
• Owns markdown quick-fix and ignore-action generation for markdownlint diagnostics.
• Does not own Markdown editor views, preview rendering, metadata extraction, or CodeMirror lint UI.
• Does not own Electron sidecar lifecycle or IPC handlers; the desktop host still owns those capabilities.

Runtime Contract

• Consumes app.languageServices.registerProvider(...).
• Consumes app.configuration.getConfiguration() to resolve vault-scoped disabled rules on demand.
• Uses @lapis-notes/language-service for both worker-backed and native-bridge markdown provider factories.
• Probes the shared native desktop bridge through @lapis-notes/api before attaching the native markdown provider.

This makes markdownlint a plugin-owned feature even when the underlying implementation uses a host-owned Electron sidecar.

Current Limitations

• Host-aware selection between worker-backed and native-desktop markdownlint still lives in package code rather than purely in manifest metadata.
• The current settings treatment is the shared Core plugins surface, not a richer dedicated markdownlint UI.
• Quick fixes currently surface per-diagnostic markdownlint edits; workspace-wide fix-all and formatter parity remain separate UX work.

Search Plugin (@lapis-notes/search)

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

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

The search package owns the search sidebar, indexing controls, result rendering, semantic-search status affordance, and the plugin-level settings that shape lexical and vector retrieval. Heavy indexing and query execution are routed through AppDatabase instead of running SQLite or embedding work directly in the renderer.

View, Commands, And Settings

• View type: SearchViewType in the left sidebar.
• Commands: search-all-files, search-selected-text, open-search-left-sidebar, rebuild-search-index, refresh-semantic-search.
• open-search-left-sidebar accepts an optional query argument and seeds the Search view when called by other plugins.
• Settings: semantic provider, embedding model id, remote/local model policy, explicit embedding rebuild, chunk target size, breakpoint search window, breakpoint decay, result limit, snippet length, match-case mode, recent searches, sidebar presentation options, plus a disabled-by-default Electron-only query-enhancement contract that is persisted for future local expansion/reranking but is not yet exposed in the UI.

Search State

File-level records include path, name, extension, checksum, tags, tag parts, tag hierarchy, and serialized frontmatter metadata text.

Chunk records include stable chunk id, source path, ordinal, source offsets, nearest heading or section label, chunk content, and optional embedding state. Ready embeddings are mirrored into the SQLite vec table in SQLite-backed sessions.

Key Behaviors

• Derives markdown-aware chunks from cached headings, sections, and frontmatter-aware source positions.
• Listens to metadata cache changed and deleted events for reactive updates and background embedding invalidation.
• Indexes visible JSON Canvas node and edge text from .canvas files during refresh and canvas vault create/modify/delete events.
• Retries startup embedding backfill when provider configuration lags initial layout so persisted semantic-search state eventually resumes without a manual refresh.
• Starts provider warmup as soon as an embedding provider is configured, but treats startup provider configuration as best-effort post-mount work so proxy-session database delegation cannot block the rest of app boot.
• Refreshes searchable markdown files even when metadata cache entries are still unavailable by indexing them with empty source-metadata snapshots until later metadata events enrich the stored search document.
• Vault-driven semantic refresh also prunes stale generated search documents whose paths are no longer present in the current vault file list, so footer status and pending-chunk counts can recover from missed delete events or older failed runs.
• Debounces metadata-cache changed and deleted events by source path so rapid edits collapse into bounded search-index updates and the latest content wins before the write reaches AppDatabase.
• Wraps vault refresh indexing in AppDatabase search batches when the active backend supports them and yields to the UI thread between refresh items so long-running semantic refreshes do not monopolize the renderer event loop.
• Delegates rebuild and query execution to AppDatabase.
• Supports quoted property filters for exact and nested metadata paths, including nested object and array values such as ["project.name"] and ["items.name"].
• Reports search index rebuilds and semantic-refresh backfills through app.notifications so long-running background work appears in the shared status-bar progress item and notification center. Errors are persisted as app notifications.
• On Electron, simple lexical candidate selection can be served by the native SQLite FTS path behind AppDatabase; the search UI and query syntax do not fork by runtime.
• SQLite-backed candidate builders quote generated prefix terms and split punctuation-heavy input such as hyphenated or underscored words before passing it to MATCH, avoiding FTS syntax errors while leaving final result semantics to the shared evaluator.
• SQLite-backed candidate queries use deterministic rank/path ordering before the shared evaluator performs final scoring.
• Electron native search keeps structured, case-sensitive, vector, and hybrid modes on the shared evaluator over mirrored documents, with native smoke coverage for those parity paths.
• Electron vector and hybrid searches use native sqlite-vec candidates when a compatible extension is available, then fall back to the shared in-memory vector scorer when it is not.
• The plugin now persists an Electron-only local query-enhancement request contract and forwards it to AppDatabase.searchDocuments() only when it is explicitly enabled and the runtime is Electron. The current implementation still keeps UI controls hidden and reports enhancement as unavailable until a runnable local model/reranker provider exists; strong lexical or hybrid RRF results are treated as an automatic skip condition.
• Registers embedded markdown query code-block rendering backed by the same search manager.
• Returns grouped file results with snippet text, explicit highlight ranges, chunk offsets, backend provenance, lexical-versus-semantic mode, and explainable RRF score breakdowns for hybrid ranking.

UI Ownership

The search view uses a CodeMirror query editor backed by the shared API search-query language, focus-time search option help, wrapper-click focus forwarding that keeps the query caret visible on first focus, operator autocomplete, vault-backed path:, file:, and tag: value autocomplete, fixed query controls, a scrolling results area, a copyable total-result summary, result sorting with responsive trigger truncation, match-case control, recent-search recall from the empty-query sidebar and with ArrowUp / ArrowDown when the caret is at the start of the query, inline presentation settings, explicit snippet highlighting, and click-to-open result navigation.

The semantic-search status-bar item remains a search-specific diagnostics surface for provider readiness, chunk counts, model download status, and embedding health. Status reads now prefer incremental app-database search stats instead of rescanning the full stored search corpus on every poll while indexing is active. Generic active-work visibility belongs to the shared notifications plugin.

The package follows the Plugin CSS Contract with workspace dist/app.css, standalone dist/styles.css, search-view__..., search-status..., and search-highlight selectors.

Related Docs

• Obsidian Search Parity
• Storage, Metadata, and Search

Obsidian Search Parity

This page tracks the intended search-query and search-UI parity target for the bundled search implementation against Obsidian’s Search plugin documentation at https://obsidian.md/help/plugins/search.

The goal is not to clone every internal implementation detail. The goal is to preserve the user-visible query language, result semantics, and core sidebar workflows closely enough that Obsidian search terms transfer directly.

Upstream Feature Areas

Obsidian’s documented Search plugin behavior covers these main areas:

• Search terms: word conjunction, exact phrases, OR, parentheses, negation, and regex.
• Search operators: file:, path:, content:, match-case:, ignore-case:, tag:, line:, block:, section:, task:, task-todo:, and task-done:.
• Search properties: [property], [property:value], [property:null], property comparisons such as [duration:<5], and grouped or regex subqueries inside property values.
• Search UI behavior: explain search term, collapse results, more context, sort order, recent searches, copy search results, and the sidebar search workflow.
• Search scope: notes and canvases, with embedded query code blocks as a separate rendering surface.

Current Parity Matrix

Implemented Today

The current implementation is strongest in these areas:

• Shared search-query grammar and AST ownership in packages/api.
• Phrase-aware lexical search, regex literals, boolean grouping, negation, and search-term explanation.
• Frontmatter-key existence, value, null, comparison, and nested property queries.
• Field, case-mode, line, block, section, and task-scoped operator execution.
• Sidebar presentation settings and sort options.
• Recent searches, selected-text handoff, copy-results action, canvas indexing, and embedded query blocks.
• Hybrid lexical plus semantic retrieval infrastructure behind AppDatabase.

These pieces provide the current user-visible Obsidian search parity target while leaving performance and presentation refinements available for follow-up work.

Remaining Caveats

The implemented parity layer intentionally stays within the app’s current generated search model:

1. SQLite-backed sessions route structured or case-sensitive lexical queries through the shared evaluator over the mirrored in-memory search document set so semantics stay consistent across database backends.

2. Same-block and same-section matching uses text-derived block and heading regions. It does not yet require a markdown parser section record for every match.

3. Canvas search indexes visible JSON Canvas node and edge text, linked files, and URLs. It does not inspect the contents of files referenced by canvas nodes unless those files are indexed separately.

4. Embedded query blocks render a compact clickable result list and intentionally reuse the search plugin’s current lexical query path.

Follow-On Refinements

Further work can improve performance and polish without changing the user-visible query contract:

1. Lower structured field and property filters into SQLite candidate queries before evaluator scoring for large vaults.
2. Prefer cached markdown section metadata for block: and section: when all indexed documents carry complete section spans.
3. Add richer embedded-query block chrome such as result counts, snippets, and sort controls.

Tasks Plugin (@lapis-notes/tasks)

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

Package: @lapis-notes/tasks. Manifest: id tasks, version 0.0.1, min app version 1.7.7.

The tasks package owns browser-first task capture and management as a bundled first-party plugin. It is currently a transitional implementation that is being aligned to TaskNotes’ markdown-first model without relying on desktop-only integrations or Obsidian internal APIs.

This package is a vendoring of the upstream TaskNotes plugin into Lapis Notes. That upstream plugin should be treated as the implementation reference for any functionality we decide to support here, while the standalone TaskNotes specification remains the behavioral contract for markdown model semantics.

TaskNotes Direction

TaskNotes is explicitly markdown first: the intended end state is one markdown note per task with YAML frontmatter for machine-readable properties and note body content for freeform detail. The standalone TaskNotes specification is the behavioral contract for future read/write semantics, especially around model mapping, operations, temporal fields, recurrence, validation, configuration, dependencies, reminders, and links.

For future feature work, start from upstream TaskNotes behavior and data flow first, then adapt it for this host only where browser constraints, shared package boundaries, or non-Obsidian runtime differences require a documented deviation.

The current plugin now claims the TaskNotes core-lite conformance profile through a dedicated adapter bridge. The primary storage model is markdown first and supports persisted folder and field-role configuration plus stricter validation, while advanced TaskNotes semantics remain intentionally out of scope.

See Upstream Feature Audit for the current gap inventory and phased roadmap derived from upstream TaskNotes docs and source references.

Implementation Sequence

Vendoring proceeds in ordered slices instead of a wholesale upstream import:

1. Keep the current first-party Lapis plugin shell, workspace boot wiring, and @lapis-notes/ui-based Tasks view.
2. Unwind the current non-conforming primary model by removing JSON-backed manual tasks and generic checklist aggregation from the main Tasks dataset.
3. Replace transitional storage with markdown-first TaskNotes task-note writes and task-folder indexing.
4. Add TaskNotes semantic field mapping, browser-safe configuration handling, and strict validation for the supported core behavior.
5. Add TaskNotes fixture or conformance-backed validation before expanding into recurrence or other advanced features.

The first six slices are now in place, and the adapter now also covers the current core-lite bridge surface. The remaining roadmap is now split into concrete feature families: schema/settings parity, richer editor and inline-capture surfaces, remaining Bases parity, recurrence/dependency/link semantics, time-management surfaces, and host-constrained external integrations.

Registration

• View type: plugin:tasks.
• Settings tab entry: Tasks, which renders the persisted task settings form directly in the plugin settings panel.
• Command: tasks:open-view.
• Commands: tasks:open-task-list-base, tasks:open-kanban-base, tasks:open-fizzy-base, tasks:open-fizzy-calendar-base, and tasks:open-mini-calendar-base.
• Ribbon action: opens the Tasks view.
• Core-plugin activation through the workspace shell.

Data And Persistence

The current slice stores each task as a markdown note in a configurable managed task folder, defaulting to TaskNotes/Tasks/. Supported task-note frontmatter roles currently include:

• title
• status
• priority
• due
• scheduled
• tags
• projects
• blockedBy
• recurrence
• recurrenceAnchor
• completeInstances
• skippedInstances
• timeEntries
• dateCreated
• dateModified
• completedDate

The task identifier is currently derived from the note path rather than stored as a separate frontmatter field. The plugin indexes the configured task-note folder as its primary dataset, also indexes markdown notes outside that folder when the task parser accepts them and their mapped frontmatter tags include the configured task tag, persists folder and field-role settings through plugin data, creates missing folder paths in a browser-safe way, and updates task status, priority, scheduled dates, relationship links, Fizzy pin or golden state, and other frontmatter-backed task properties by mutating mapped frontmatter fields through the vault API with the same path-aware semantics used by the shared Properties and FrontMatter editors, automatically touching dateModified whenever one of those mutations changes task frontmatter. The initial full-vault rebuild now gathers candidate note content on the host thread but offloads bulk task-note parsing and index construction to a dedicated worker with a main-thread fallback if worker startup fails. Strict validation now also enforces required temporal fields, completedDate conditional requiredness, due-value parsing, and dateModified >= dateCreated ordering for the currently supported model.

The persisted settings model now also carries a broader schema foundation for later TaskNotes parity work, including:

• extended frontmatter-role mapping for scheduled dates, contexts, projects, time estimates, recurrence, reminders, blockers, and time entries
• title-storage configuration for frontmatter vs filename-based titles
• default task values and task-detection strategy data
• richer status and priority vocabularies
• Fizzy board preferences for Not Now status, entropy enablement, and entropy age; pinned card state is persisted in task-note frontmatter as pinned: true/false rather than in plugin settings
• custom user-field definitions with NLP and suggestion-filter metadata
• modal field-group layout metadata

The Tasks settings tab now exposes the persisted managed folder, marker tag, title-storage mode, filename strategy, default status/priority/date presets, task-detection rules, Fizzy Not Now lane, Fizzy entropy controls, status and priority vocabularies, and JSON-backed custom fields directly inside the plugin settings panel. The interactive runtime also now uses that persisted schema for creation defaults, preset recurrence rules, recurring completion history, mapped reminder visibility, dependency readiness state, Fizzy frontmatter-backed pin state and entropy moves, and timeEntries-backed task timers. Modal field-group editing and richer schema-specific editors remain future work.

UI Ownership

The first view slice is a dedicated Tasks leaf with:

• toolbar Add task dialog for task-note capture (preserves #tasks-title, due date, and tags for E2E); settings configuration lives in Settings → Tasks, not an inline settings card
• command-driven inline task conversion from the current Markdown editor line, a single-line selection, or all supported prefixed task lines in the current note into TaskNote links
• partial metadata extraction during inline conversion for hashtags and explicit ISO due-date tokens
• reading-mode convert affordances for promoting supported prefixed Markdown task candidates into TaskNotes
• source-mode and live-preview convert affordances for promoting supported prefixed Markdown task candidates in place
• task-note summary widgets in reading mode, source mode, and live preview for indexed task notes, including markdown notes outside the managed task folder when their mapped frontmatter tags include the configured task tag and the task parser accepts them, now rendered through a reusable upstream-shaped task-row surface with an upstream-style cycling status button (none -> open -> in-progress -> done) that emits app toasts, centered priority/menu affordances, completed-row dimming, an inner hover surface that preserves a visible outer gutter, scheduled-date metadata buttons and the overflow Schedule submenu both driven by an upstream-style popup menu with increment/basic/weekday sections plus Pick date & time... and Clear date, where Pick date & time... opens a shared @lapis-notes/ui date-time picker dialog, YAML tag metadata from the mapped note tags field rendered immediately beside the scheduled chip with markdown tag styling, including the task tag when it is present on the note, due metadata pills, mapped reminder metadata pills, priority none, preset recurrence actions that write mapped recurrence fields, recurrence-aware completion that rolls the next due or scheduled date forward while recording completeInstances, a Skip next occurrence recurrence action that advances the current recurring instance while recording skippedInstances, recurring history metadata pills that surface the latest completed or skipped recurrence instance, dependency readiness metadata pills that surface blocked, ready, and blocking state from the resolved task relationships, a task-card start/stop timer button with tracked-duration pills backed by timeEntries, and a richer overflow menu for status, priority, scheduling, reminders, dependencies, organization, recurrence, copy, open, and delete actions. The dependency and organization sections open a shared @lapis-notes/ui command dialog with fuzzy search and match highlighting (same interaction model as the workspace command and file palettes) for blocker, dependent, project, and subtask linking instead of expanding every candidate task in nested submenus; reminder actions still mutate mapped reminders, and the note-widget variant now renders dedicated Reminders and relationship detail content with reminder entries, nested blocked-by and blocking task cards, linked projects, and recursive subtask rows using indentation guides instead of section labels, without a Relationships header or Open relationships entrypoint. When either panel would render, both stay collapsed by default behind a shadcn Collapsible with a hover-only chevron beside the overflow menu and click-to-expand on the card surface, while collapsed relationship summary pills remain visible in the main metadata row and hover feedback scopes to the whole card when collapsed or to individual sections and nested child cards when expanded.
• a dedicated Tasks settings-tab form that writes the persisted TaskNotes-style schema through updateSettings() so folder/tag/title/defaults/detection/vocabulary changes are available without direct test-only runtime calls
• task-link overlays in reading mode, source mode, and live preview that now reuse the same task-row family in a smaller inline layout instead of a separate compact pill surface, keeping a single compact row with status, priority, title, always-visible details and overflow actions that open the shared task detail dialog for relationship stacks and metadata instead of rendering relationship pills inline, and inactive CodeMirror source/live-preview lines that replace the raw [[...]] task link text with the overlay widget instead of showing both
• parsed relationship-link groundwork for projects and blockedBy, with runtime helper lookups for derived subtasks, blockers, and blocked-by tasks so future recursive trees and relationship widgets can build on the indexed markdown task-note dataset
• generated TaskNotes-style .base files under the managed task views folder, defaulting to TaskNotes/Views/, including a generated Fizzy base; the Fizzy view settings now expose labeled controls for the column property, Maybe and Not Now column values, title property, and hide-empty-columns toggle through the shared Bases settings sidebar
• custom task-focused Bases renderers for Task List, Kanban Board, Fizzy, Fizzy Calendar, and Mini Calendar views, registered through Plugin.registerBasesView() and rendered from the BasesQueryResult supplied by plugin-bases; task-specific views consume the already filtered and grouped Bases dataset instead of rebuilding or re-filtering task entries locally, keep a reactive snapshot of the latest Bases query result, and also invalidate themselves when the Tasks runtime emits tasks-changed so late query refreshes, task-index rebuilds, and frontmatter mutations repopulate open task Bases views; Task List and Kanban Board rows now use the full note-widget task-card surface with inline metadata, increased outer view padding, and a hover-only details button that opens a medium-width task detail dialog with header status/priority badges, note body, relationship stacks, and a built-in-properties sidebar that surfaces interactive status, priority, scheduled, due, recurrence, reminder, timer, and timestamp controls together with linked projects and blockers rendered through NoteLink where a task note target exists, plus Bases-provided extra properties, instead of compact rows or an embedded task card, while the generated Fizzy .base now persists board-specific view config including the column-driving property, special Maybe and Not Now values, user-arranged column order, and per-column title/color overrides, and the generated Fizzy Calendar .base adds an activity timeline that derives Added, Updated, and Done lanes from each task note’s current dateCreated, dateModified, and completedDate metadata rather than a durable event log, collapsing consecutive empty visible days into a single gap row when Show empty days is enabled
• a Fizzy board renderer inspired by Basecamp Fizzy (“Kanban as it should be”) that now groups the markdown task-note dataset by a configurable metadata property, defaulting to the mapped status field, while still supporting dedicated Maybe and Not Now values plus completed columns; the board applies an optional entropy move from stale tasks into Not Now on open, resolves column colors from either configured status colors or persisted per-column overrides, applies each column color to every card in that lane instead of deriving card backgrounds from priority, supports @dnd-kit/svelte-backed drag-and-drop moves across every column by mutating the configured note property instead of hardcoding status writes, keeps only fixed column positions non-reorderable, exposes a compact inline column-action popup for moving workflow lanes left or right and editing persisted title or color metadata, renders frontmatter-backed pinned cards (pinned: true/false) in a bottom pin stack, uses explicit frontmatter-backed golden tickets (golden: true/false) instead of highest-priority inference, provides full-screen per-column grid and card detail views, embeds the reusable editable markdown preview/editor for the task-note body inside detail together with the reusable task-card controls beneath the title, supports inline detail-title edits that write back to the task note, preserves Done and Not Now stamps plus entropy countdown copy, scopes Fizzy keyboard shortcuts to the active visible board or detail surface instead of document-wide handlers, hands lane search off through the shared Bases query controller, and keeps the page root height-locked with independent column scrolling
• Task-focused Bases view chrome, including Fizzy board, detail, and calendar surfaces, now ships through the Tasks package stylesheet artifacts (app.css and styles.css) rather than component-local <style> blocks; runtime values such as per-card or per-column colors are passed through CSS custom properties that those external styles consume so the same override surface is available in both workspace and standalone builds
• Tasks styling inherits the shared Obsidian-aligned global theme through core background, border, text, accent, warning, success, and error variables. Task-specific variables keep status, due-date, recurrence, and relationship semantics distinct without defining a separate app palette.
• Tasks leaf toolbar Task views dropdown that creates or opens the generated task Bases files through the shared Bases runtime (replacing the former Views card)
• local create-form validation and inline submission errors for task-note capture in the toolbar dialog
• a shadcn-svelte-style data table as the primary browse surface (see Tasks leaf browse surface below and task id TASK-PLUGIN-018)
• completion toggling, deletion, note-open actions, and task-note path badges through table rows and the shared task-card overflow menu
• shared @lapis-notes/ui controls for form fields, data table, table, badges, and actions
• namespaced tasks-... selectors for plugin-owned styling

Tasks leaf browse surface

Tracked as TASK-PLUGIN-018. The main Tasks leaf (plugin:tasks) uses a data-table-first layout aligned with the shadcn-svelte tasks example:

flowchart TB
  header[Header: title + stats]
  toolbar[Toolbar: search + filters + Add task + Views + columns]
  table[Primary data table]
  pagination[Pagination footer]
  header --> toolbar --> table --> pagination

The toolbar provides search, status/priority faceted filters, reset, column visibility, Add task, and Task views. Row filtering reuses filterTasks() at the view level. The overflow menu is shared between table row actions and task-card surfaces. Bulk row selection and new @lapis-notes/ui faceted-filter primitives are out of scope.

Future upstream-style audits for task-row surfaces must compare the rendered widget DOM against the upstream TaskCard implementation surface, not just the visible controls and token palette. That audit must cover styles/task-card-bem.css, the TaskCard status-cycle/runtime wiring, taskCardProperties metadata renderers, the upstream DateContextMenu popup structure, status and priority settings vocabularies, and the upstream task context menu action set. Alignment, hover hit-area placement, metadata text sizing and color, tag rendering, state vocabulary, overflow-menu breadth, and scheduled-date menu grouping are part of the feature contract.

Task completion updates TaskNotes-style frontmatter through the vault API instead of maintaining plugin JSON state or inline checklist mirrors.

The package now also carries source-level conformance status metadata targeting tasknotes-spec 0.1.0-draft, documenting current configuration providers, core-lite capabilities, and known deviations. It exposes a dedicated ESM conformance adapter entrypoint alongside adapter-style meta.*, date.*, field.*, config.*, validation.*, create_compat.create, op.*, delete.remove, task.load, task.create, and the existing internal OP.* mutation aliases.

This slice is intentionally browser-safe and self-contained. It does not depend on community-plugin compatibility shims, desktop-only HTTP/OAuth flows, or internal embed/editor APIs.

Shared UI primitives for this package should come from @lapis-notes/ui. If the plugin needs an additional control, it should first be added to @lapis-notes/ui using the existing shadcn-svelte / Bits UI wrapper approach before introducing a plugin-local control implementation.

Things-Like Planner Workflow

A Things-like planner workflow now ships as a Lapis-specific layer over the existing markdown-first Tasks runtime. It helps users decide what deserves attention now without replacing the existing Tasks data table, generated Bases views, task-card widgets, recurrence/reminder/dependency behavior, or Fizzy board workflows.

The planner is implemented first as a dedicated workspace view backed by the Tasks runtime (getTasks() plus tasks-changed). A generated Planner Base now ships as a companion query surface, but the daily workflow still lives in the first-class planner view rather than in a database browser.

The planner buckets are:

Due dates and scheduled dates must stay distinct. A due date is a deadline; a scheduled date is the date a task should become available or planned. The default planner model should not treat due-today tasks as Today commitments, though a later setting may add that behavior as an explicit option. Someday must be explicit planner metadata; undated tasks should classify as Inbox or Anytime.

The planner metadata layer now includes mapped when, areas, todayOrder, projectOrder, projectSection, and reviewed fields. The planner settings surface persists the default planner bucket, due-today inclusion, Anytime review threshold, Someday review threshold, and the mapped field names for those planner-specific properties.

The dedicated planner view now owns:

• quick Inbox capture that bypasses date defaults
• a settings-pane-style resizable sidebar and independently scrolling main pane, with a draggable divider that does not show a visible grip icon
• planner scheduling actions for Today, This Evening, Tomorrow, This Weekend, Next Week, Someday, and Clear
• first-class area and project side rails with linked task views
• a persistent Areas rail section that remains visible even before any area-linked task exists
• compact planner rows that show a checkbox, title, and minimal metadata in the collapsed state
• double-click row expansion that opens a frontmatter-hidden inline live-preview editor, focuses an editable title field on open with the caret at end, keeps the expanded row stable while focus moves between the title, body editor, and footer actions, dismisses only from planner list/body background clicks or a different task row while ignoring app chrome, sidebars, planner headers, capture controls, expanded-row content, and portaled menus or dialogs, animates close/open switching so double-clicking a different row closes the old panel before opening the new one without losing the second click target, and preserves the task note’s frontmatter on write
• expanded-row footer actions for planner placement, due/deadline editing and clearing, area/project assignment, full detail opening, note opening, and overflow task actions
• Upcoming calendar rows that show the date number and weekday, insert month dividers, and collapse longer empty spans such as June 4-30
• manual ordering in Today and project lists through drag-and-drop plus move up or down controls
• project sections persisted in task frontmatter and edited from project views
• a review surface that highlights Inbox triage, stale Anytime tasks, stale Someday tasks, and projects without a next action, with actions to mark reviewed or re-plan the task in place

The generated Planner Base companion now creates TaskNotes/Views/Planner.base with Inbox, Today, Upcoming, Anytime, Someday, Logbook, and Deadlines views. That Base intentionally remains a companion approximation: it exposes planner metadata and the closest safe query representations Bases can express, but it does not replace the dedicated planner’s runtime-only bucketing and review logic.

Known Deviations And Gaps

• Richer relationship widgets, richer metadata extraction, and natural-language parsing are still missing. Inline task capture now covers command, reading-mode, source-mode, and live-preview conversion for supported prefixed Markdown task candidates with formatting-preserving replacements plus hashtag and explicit ISO due-date extraction, the task-note widget now renders dedicated Reminders and relationship detail content together with linked projects, nested blocked-by and blocking task cards, dependency sections, reminder metadata, blocked/ready/blocking state pills, and recursive subtask rows, and inline task-link overlays now route relationship detail through the shared task detail dialog instead of inline pills. Remaining relationship work is focused on broader dedicated widgets, deeper parity polish, and broader metadata extraction. Task IDs: TASK-PLUGIN-007, TASK-PLUGIN-011.
• Task schema/settings parity now has an interactive Tasks-view settings surface, including Fizzy controls for Not Now lane selection, entropy enable/days, status and priority vocabularies, and JSON-backed custom fields, but modal field-group editing, richer typed editors for custom fields and suggestion filters, and deeper filename-strategy parity are still missing. Task ID: TASK-PLUGIN-009.
• The initial Bases-backed task list, kanban, Fizzy, Fizzy Calendar, mini calendar, and generated default .base templates are now implemented. The Fizzy board now uses frontmatter-backed pins and golden tickets, property-driven column grouping with persisted column-property and Maybe/Not Now value config in the generated .base, persisted per-column title/color overrides, drag writes against the configured note property, detail-screen editable markdown plus inline title editing with a footer Edit action and e shortcut that enter body-edit mode, Done and Not Now stamps, entropy countdown copy, full-screen detail and grid views, and demo-faithful layout/interactions. The Fizzy Calendar view now adds an activity timeline grouped into Added, Updated, and Done columns, keeps the page root height-locked with its own vertical scrolling surface, reuses the shared task-card body inside each calendar card, uses a dedicated day-window slider for its recent activity range, and still derives that activity from current task metadata instead of a durable historical event stream. Remaining Fizzy work includes comments, boosts, richer task-card overflow-menu reuse, manual card ordering within lanes, and deeper activity-history parity. Task IDs: TASK-PLUGIN-010, TASK-PLUGIN-015, TASK-PLUGIN-016, TASK-PLUGIN-017.
• The Things-like planner workflow is now implemented as a dedicated Tasks planner view plus a generated Planner Base companion. The dedicated view owns the refined Things-style interaction model, including the resizable planner sidebar, compact expandable rows, inline body editing, Areas and Projects side rails, review projections, calendar-like Upcoming grouping, and sparse ordering. Current limitations are intentional: the generated Planner Base exposes the closest safe query views Bases can express, while runtime-only bucketing, review projections, inline row editing, and sparse ordering still live in the planner view itself.
• Recurrence now has preset rule selection plus rolling completion or skip-forward actions for the managed due or scheduled field, and the browse/task-row surfaces now show the latest recurring completion or skip date, mapped reminder metadata, explicit due-date, day-before-due, scheduled-date, and picked reminder actions, a note-widget bell reminder indicator with tooltip, lightweight dependency readiness state, and collapsible note-widget relationship stacks, but custom rules, richer skip-state UX, broader reminder automation semantics, broader relationship widgets, richer link semantics, and the extended TaskNotes conformance profiles remain unimplemented. Task IDs: TASK-PLUGIN-006, TASK-PLUGIN-011.
• Time tracking now has an initial task-card start/stop timer surface backed by timeEntries, but calendar editing, richer auto-stop policy controls, Pomodoro views, calendar integrations, ICS subscriptions, and automation surfaces are still missing or blocked on host-capability decisions. Task IDs: TASK-PLUGIN-012, TASK-PLUGIN-013, TASK-PLUGIN-014.
• Any intentional divergence from upstream TaskNotes plugin behavior for browser-host or package-boundary reasons must be recorded here before implementation is treated as complete.

Tasks Upstream Feature Audit

This page inventories the remaining gap between the vendored @lapis-notes/tasks package and the upstream TaskNotes plugin, then turns that gap into an ordered implementation roadmap.

It is based on upstream TaskNotes documentation and source references, especially:

• tasknotes.dev/core-concepts/
• tasknotes.dev/features/inline-tasks/
• tasknotes.dev/features/time-management/
• tasknotes.dev/features/calendar-integration/
• tasknotes.dev/views/
• tasknotes.dev/views/default-base-templates/
• tasknotes.dev/views/kanban-view/
• tasknotes.dev/views/calendar-views/
• tasknotes.dev/views/pomodoro-view/
• tasknotes.dev/settings/task-properties/
• tasknotes.dev/settings/modal-fields/
• upstream source in callumalpass/tasknotes, including src/editor/TaskLinkWidget.ts, src/editor/InstantConvertButtons.ts, src/bases/KanbanView.ts, src/bases/CalendarView.ts, src/views/PomodoroView.ts, and src/templates/defaultBasesFiles.ts

Current Lapis Coverage

The current vendored package covers only the first TaskNotes slice families:

• markdown-first note-per-task storage
• folder and frontmatter-role mapping
• strict validation for the current minimal model
• a first-party Tasks list view using shared @lapis-notes/ui components
• a core-lite conformance bridge for the current markdown model and operation subset

That leaves most upstream user-facing surfaces still missing.

Missing Feature Families

Task-Note Editor Surfaces

Upstream TaskNotes augments task notes and task links directly inside Markdown views:

• interactive task-link overlays in reading mode and live preview
• task-file widgets in task notes, including the relationships widget backed by relationships.base
• task-aware quick actions that can mutate status, dates, and metadata at the link location

Lapis Notes now has a reusable task-row family across task-note widgets and task-note links in reading mode, source mode, and live preview. The current slice exposes an upstream-shaped single-row contract with checkbox completion, priority selection, scheduled-date quick options plus a custom date-time picker entry point, metadata pills, and an overflow menu through the existing Markdown widget mount paths. Relationship-model groundwork now also parses projects and blockedBy links into runtime lookups, the task-row menus now mutate those mapped relationship fields directly through the task-note frontmatter write path, the browse/task-row surfaces now show reminder metadata together with blocked/ready/blocking dependency state, the overflow menu now exposes explicit due-date, day-before-due, scheduled-date, and picked reminder actions through the mapped reminders field, the note-widget variant now renders a dedicated Reminders panel that lists each mapped reminder plus a dedicated Relationships panel with summary counts, nested blocked-by and blocking task cards, an Open relationships base entrypoint, linked projects, and recursive child-task rows inline, and inline task-link overlays now surface a compact relationship summary, direct related-task pills, and the same Open relationships entrypoint. The remaining gap is rollout depth rather than feature existence: broader relationship/dependency widgets are still missing, and the full note-widget family still needs broader parity polish.

Audit note: future upstream-parity passes for task rows must verify the upstream implementation surface, not just static tokens or control presence. The previous passes matched the visible shell of the row but missed that upstream behavior is split across styles/task-card-bem.css, TaskCard runtime wiring, taskCardProperties metadata renderers, the DateContextMenu popup structure, status and priority settings vocabularies, and the task context menu action set. That gap is why later audits had to rediscover inner-hover hit areas, metadata text sizing/color, markdown-tag rendering, none/open/in-progress/done status cycling, priority none, toast feedback, menu breadth, and the scheduled-date popup grouping after the initial visual parity pass looked superficially close.

The next durable rollout order for relationship-driven task rows is:

1. broaden the current Relationships panel into fuller upstream-style relationship/dependency widgets
2. finish broader upstream parity polish for the note-widget family

Task IDs: TASK-PLUGIN-007, TASK-PLUGIN-011

Inline Task Capture And Conversion

Upstream TaskNotes integrates with the editor so checklist lines and plain content can be promoted into TaskNotes files:

• Create inline task command from the current line
• per-line convert affordances next to checkboxes and other supported line shapes
• bulk conversion of all checkbox tasks in a note
• formatting-preserving replacement of the source line with a task link
• metadata extraction and optional natural-language parsing during conversion

Lapis Notes now supports command-driven line, selection, and note-wide conversion plus reading-mode, source-mode, and live-preview convert affordances for supported prefixed Markdown task candidates. The current conversion path preserves list and blockquote structure while replacing source content with task-note links, and it extracts hashtags plus explicit ISO due dates into the mapped frontmatter model.

Task Schema, Settings, And Modal Parity

The upstream plugin exposes a much richer configurable task schema and task-editing surface than the current Lapis implementation:

• title storage in filename or frontmatter with multiple filename strategies and templates
• custom status and priority vocabularies with labels, colors, icons, and completion semantics
• richer property coverage for scheduled dates, projects, contexts, reminders, recurrence, time estimates, blocked-by links, time entries, archive tags, and feature-specific keys
• custom user fields with typed defaults and autosuggestion filters
• configurable modal field groups, ordering, visibility, and required flags
• NLP trigger configuration and capture-oriented defaults

Lapis Notes now ships a dedicated Tasks-view settings surface for the managed folder, marker tag, title storage, filename strategy, default status/priority/date presets, task-detection rules, status and priority vocabularies, and JSON-backed custom fields. Modal field-group editing, richer typed custom-field editors, and deeper filename-template parity are still missing.

Task ID: TASK-PLUGIN-009

Bases-Backed View Suite And Default Templates

Upstream TaskNotes v4 uses Bases as the main view system for task-focused navigation. The documented view suite includes:

• Task List views
• Agenda views
• Kanban views with grouping, swimlanes, drag-and-drop, and manual ordering
• Mini Calendar views
• full Calendar views with day/week/month/year/list/custom-day modes
• Relationships views backed by generated .base files
• generated default .base templates with formulas, filters, ordering, and command-to-file mappings derived from TaskNotes settings

Lapis Notes now generates and opens TaskNotes-style .base files for Task List, Kanban Board, Fizzy, Mini Calendar, and Fizzy Calendar under the managed task views folder, and it registers matching custom Bases renderers (tasknotesTaskList, tasknotesKanban, tasknotesFizzy, tasknotesMiniCalendar, tasknotesFizzyCalendar) through the public Plugin.registerBasesView() path. The Fizzy renderer adds a first-pass Basecamp-Fizzy-style status board with drag-and-drop lane moves, persisted pinning, shared search controls, keyboard navigation, and optional entropy moves into a configured Not Now lane. These task-specific renderers intentionally use the Tasks plugin’s indexed markdown task-note dataset as the source of truth so the generated views stay browser-safe and do not depend on upstream Obsidian-only Bases internals.

The remaining gap in this feature family is upstream parity depth rather than feature existence: Agenda, full Calendar, and Relationships Bases views are intentionally out of scope for the current generated suite, the Fizzy base now covers a first-pass triage-board surface, but Kanban and Fizzy do not yet implement persisted manual ordering, richer swimlanes, comments, or boosts, and the remaining calendar renderers do not yet cover the full upstream mode set.

Task ID: TASK-PLUGIN-010

Lapis Planner Workflow

The Things-like planner is a Lapis-specific workflow layer rather than direct TaskNotes upstream parity. It should sit on top of the same markdown-backed task-note runtime and keep the existing Tasks table, generated Bases views, task-card widgets, recurrence/reminder/dependency behavior, and Fizzy workflows intact.

The planner should start with a pure bucket model and mapped when metadata, then add a dedicated planner view, Things-style planning actions, Inbox capture and triage, area links, manual ordering, settings controls, project sections, a generated Planner Base companion, and an optional review workflow. The dedicated planner view is the primary daily workflow; the generated Planner Base is a later query/customization companion.

Task IDs: TASK-PLUGIN-054, TASK-PLUGIN-055, TASK-PLUGIN-056, TASK-PLUGIN-057, TASK-PLUGIN-058, TASK-PLUGIN-059, TASK-PLUGIN-060, TASK-PLUGIN-061, TASK-PLUGIN-062, TASK-PLUGIN-063

Recurrence, Reminders, Dependencies, And Link Semantics

The current core-lite bridge intentionally stops short of the richer TaskNotes model surface. Dependency and project link mutations now exist in the task-row surface, the note-widget now includes dedicated Reminders and Relationships panels, the relationship widget now renders fuller blocked-by and blocking task cards. The interactive runtime now also supports preset recurrence rules plus recurrence-aware completion or skip-forward actions that roll the managed due or scheduled field forward while recording completeInstances or skippedInstances, and the browse/task-row surfaces now expose mapped reminder metadata together with explicit due-date, day-before-due, scheduled-date, and picked reminder actions plus lightweight blocked/ready/blocking state, but the remaining missing behavior still includes:

• custom recurrence rules and richer per-instance completion/skip state UX
• broader reminder defaults and automation semantics
• deeper dependency graphs (blockedBy, blocking, relationship tabs, richer readiness checks)
• link semantics and richer note/task relationship handling
• extended conformance profiles beyond core-lite

Task IDs: TASK-PLUGIN-006, TASK-PLUGIN-011

Time Tracking And Productivity Views

Upstream TaskNotes includes time-management features that cut across task cards, views, and dedicated productivity surfaces:

• start/stop task timers writing to timeEntries
• auto-stop of active timers when tasks complete
• calendar-driven time-entry editing
• timeblocking flows
• Pomodoro timer view
• Pomodoro statistics/history view

Lapis Notes now has an initial task-card start/stop timer surface that writes timeEntries, renders tracked-duration pills, and auto-stops active timers when tasks complete. Calendar time-entry editing, timeblocking flows, Pomodoro views, and richer time-policy settings are still missing.

Task ID: TASK-PLUGIN-012

Calendar And External Calendar Services

Upstream TaskNotes blends task scheduling with external calendar systems:

• Calendar and Mini Calendar Bases views
• OAuth-backed Google Calendar and Microsoft Outlook sync
• ICS subscriptions
• drag-and-drop calendar scheduling and event rescheduling
• time-entry editor and timeblocking flows from calendar interactions

In Lapis Notes this area is partly a product gap and partly a runtime-capability decision, because browser-only delivery cannot safely absorb credential handling or background sync in the same shape as upstream Obsidian.

Task ID: TASK-PLUGIN-013

Automation And External APIs

Upstream TaskNotes also exposes automation-oriented surfaces:

• HTTP API
• webhooks
• CLI-oriented flows
• MCP-style and service-backed automation surfaces in the repo

These do not map directly onto the current browser-first Lapis host. They need an explicit capability decision before they can be sensibly vendored.

Task ID: TASK-PLUGIN-014

Proposed Sequence

1. Implement schema/settings parity first so later view, editor, and conversion work target the right frontmatter model and configurable fields. (TASK-PLUGIN-009)
2. Add inline task capture and editor/read-preview integration on top of that schema so task promotion and task-note widgets share one model. (TASK-PLUGIN-007, TASK-PLUGIN-008)
3. Build the Bases-backed view suite and generated default templates once the schema and field mapping are broad enough to drive task list, kanban, agenda, calendar, and relationships views. (TASK-PLUGIN-010)
4. Add the Lapis planner foundation after the markdown task runtime and reusable task-row surfaces are stable, starting with the bucket model plus when metadata and first-class planner view before later ordering, areas, project sections, generated Base, and review slices. (TASK-PLUGIN-054 through TASK-PLUGIN-063)
5. Expand the model into recurrence, reminders, dependencies, and link semantics, then promote conformance beyond core-lite. (TASK-PLUGIN-006, TASK-PLUGIN-011)
6. Add time-tracking and Pomodoro surfaces after task-card actions, dependency handling, and calendar entry points exist. (TASK-PLUGIN-012)
7. Tackle calendar-provider and ICS integrations only after runtime capability boundaries for auth, secrets, and background synchronization are explicitly decided. (TASK-PLUGIN-013)
8. Tackle external automation surfaces last, because they depend on the settled task model, view suite, and host-capability story. (TASK-PLUGIN-014)

Implementation Constraints

• Visible UI should continue to use Svelte components backed by shared @lapis-notes/ui primitives where possible.
• Upstream Obsidian internals should be replaced with Lapis Notes editor, Markdown, workspace, and Bases APIs rather than copied directly.
• Browser-only delivery is the default assumption. Features that require secrets, background sync, local OS integration, or long-running services should be capability-gated and may need future desktop or service companions.
• Any deviation from upstream TaskNotes behavior that changes user-facing semantics should be documented in the Tasks package page and linked back to the relevant task id when one exists.

Bases Plugin (@lapis-notes/bases)

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

Package: @lapis-notes/bases. Manifest: id bases, version 0.0.1, min app version 1.7.7.

The bases package owns structured data views over Markdown files and opens .bases and .base documents through BasesViewType. The package now also mounts the same query-and-view pipeline into markdown-owned read-only surfaces: .base and .bases file embeds render inline through the markdown embed registry, and fenced base or bases code blocks render the fence body as an inline read-only Bases document.

Data Model

type BasesPropertyType = "note" | "formula" | "file";
type BasesPropertyId = string | `${BasesPropertyType}.${string}`;
type SortColumn = { property: string; direction: "ASC" | "DESC" };
type FilterLine = { column: string; op: string; value: unknown };

type BasesDocument = {
  filters: unknown;
  properties: unknown[];
  formulas: unknown[];
  activeView: string;
  views: BasesView[];
};

Table views track column sizing, table/card layout, row height, card size, image configuration, image fit, and image aspect ratio.

Query And Rendering

The plugin integrates PEaQL, but QueryController no longer builds every candidate row directly from metadataCache.fileCache up front. It first asks app.appDatabase.queryIndexedMetadata() for a plugin-neutral indexed metadata row set, lowering only conservative conjunctive constraints such as folder prefixes, file extensions, tag requirements, property existence, scalar property comparisons, and supported file or property sorts. Returned rows are materialized back into VaultRecord objects before PEaQL executes over the BasesTable database context, so the renderer still owns final query semantics while AppDatabase can narrow and order the candidate set in worker or native SQLite-backed runtimes. When the AppDatabase query path is unavailable or fails, Bases falls back to the previous metadata-cache-derived renderer snapshot.

Indexed-Metadata Pushdown

Current Bases documents do not compile the full filter or formula surface into AppDatabase. The current pushdown boundary is:

Unsupported or unlowered clauses do not disable Bases queries. They simply are not pushed into AppDatabase, and PEaQL still applies the full Bases semantics in the renderer over the loaded candidate rows.

Explicit note.* properties declared in a Bases document and observed frontmatter keys inferred from rows are both materialized into the structured note.* query schema, which keeps generated plugin-owned .base documents and raw predicates like note.status compiling against the structured note object.

Rendered views include a TanStack Table data grid with sizing, sorting, filtering, visibility, and cell editing, plus a card/grid renderer with configurable image handling. Card image fields resolve string, wikilink/embed, markdown-image, and file values to vault image files and render them through Vault.getResourceUrl(), so Electron uses the scoped native resource protocol while browser vaults keep blob URL fallback behavior. Toolbar filter state, counts, and popover rows reflect both document-wide filters and view-local view.filter predicates, including structured filter-line objects such as inFolder rules stored in .base documents. Metadata invalidation is owned by QueryController rather than by each child renderer: a base now reacts once per metadata event and uses conservative dependency tracking over the current filters, visible or sorted properties, group-by state, and direct file-reference neighborhood to decide whether it needs to rerun the query. Static file-path fields such as file.name and inFolder no longer force a vault-wide reload on unrelated metadata changes, while mutable file fields such as file.mtime, custom formulas, and direct-link neighborhoods still keep the broader conservative fallback. The Sort popover and table column headers now both use @dnd-kit/svelte drag handles, so Bases keeps one drag stack for sort-clause and column-order reordering while persisting updated view.order values back into the .base document. The built-in Bases view registry also merges external view registrations supplied through Plugin.registerBasesView() so other plugins can contribute Bases-specific layouts through a public runtime path. Custom view registrations now persist across plugin startup order, and the Bases document normalizer preserves non-built-in view type ids when .base files round-trip through source mode, so generated plugin-owned task views can reopen without collapsing to the unknown-view fallback. Markdown-hosted embeds and fenced Bases blocks intentionally mount the same renderer in a read-only configuration: they reuse query execution, sorting, grouping, and rendering, but they do not write source document edits back through the vault or expose the file-view source/preview mode switcher.

Tag cells use the shared @lapis-notes/ui/tag renderer so Bases tag chips match Markdown preview tags and metadata property chips.

The shared Bases view-settings panel renders labeled controls for plugin-registered dropdown, slider, property, text, and toggle options, so custom .base views can expose editable per-view configuration directly from the sidebar. Filled check indicators in Bases popovers use --interactive-accent with --text-on-accent so selected property, group, sort, and visibility controls keep readable foreground contrast under custom themes.

CSS Ownership

The package follows the Plugin CSS Contract with workspace dist/app.css, standalone dist/styles.css, and bases-... selectors across the shell, toolbar, table, card/list, summary, and error surfaces.

Related Docs

• Bases Parity Audit

Bases Parity Audit

This note audits the current Bases implementation in this repository against two upstream references:

• Obsidian API types from obsidian.d.ts v1.12.3
• Obsidian help pages for Bases, Views, Syntax, Functions, and Formulas

The audit covers two local surfaces:

• the shared compatibility API in packages/api/src/lib/bases.ts
• the working runtime in packages/plugins/plugin-bases/src/

The main finding is that the repository has partial Bases coverage, but parity is split across two different implementations:

• @lapis-notes/api exports a compatibility-oriented Bases surface with several type and helper shims
• plugin-bases owns the actual .base and .bases runtime, query execution, toolbar, and built-in views

That split means the repo currently has name-level parity in some places without behavior-level parity.

Progress since the initial audit

The first parity follow-up slice has landed since this note was originally written.

Completed work:

• the shared API now carries the richer DateValue and DurationValue helpers that had previously lived only in the plugin-private model, including parsing, relative/date-only helpers, duration math, and millisecond conversion
• the shared config and option surface now includes formulas, summaries, groupBy, recursive filter unions, and the upstream-style options?: (config) => ... callback shape
• plugin-bases now consumes shared BasesPropertyId, shared BasesViewConfig, and shared view option types in more of the runtime surface instead of maintaining separate local copies
• the function gap list is now backed by an executable plugin test in src/bases-view/functions-parity.spec.ts, which locks in the currently supported names and makes regressions visible immediately
• plugin-bases now has a dedicated vitest.config.ts, which makes these TypeScript-only parity checks runnable without bringing up the package’s Svelte/Vite browser test path
• the runtime now exposes additional file-derived metadata columns for file.links, file.embeds, file.backlinks, and file.properties, backed by focused tests around the shared derivation logic
• the runtime now threads groupBy into its query result model so groupedData is populated when a Base view config includes a grouping key, backed by focused tests around the grouping helper, and the query generator now also projects the active group key even when that property is hidden from the table order so grouped renderers do not collapse into Ungrouped
• the plugin now registers a built-in list view and includes a grouped list renderer with compact unordered-list rows built from the selected columns, reducing the built-in view gap to map
• the plugin now also registers a first-class map view with an explicit unsupported-state renderer, so all documented built-in layout names are present even though real map capability is still missing
• the source-to-preview document normalization path now preserves first-class cards views instead of dropping them during YAML reloads, so newly added card views survive mode switches
• grouped cards views now keep their section headers sticky within the scrolling cards pane, matching the existing grouped list/table behavior more closely
• grouped list and cards sections can now be folded from their sticky headers using local per-view collapse state
• grouped table views can now also be folded from either the inline group row or the sticky active-group header while keeping the virtualized table body in sync
• the documented file-property list is now fully exposed in the runtime, including the explicit file.file self-reference field
• the shared API now implements BasesView.createFileForView() using the existing file-manager path allocation, optional frontmatter processing, and file-opening flow
• the plugin toolbar now surfaces create-new-file through a direct New button, while copy/export CSV actions live in the result-limit popover backed by the same createFileForView() and CSV serialization helper flows
• preview-mode Bases config edits now write the serialized .base document back to the underlying file immediately instead of waiting on the editor’s debounced autosave path, which keeps newly added views from disappearing on quick reloads
• the plugin toolbar now exposes a search toggle that opens a search panel above the active view while filtering the current result set across the displayed properties, the toolbar result count now continues to reflect the underlying query result size instead of the transient search subset, and the search input now keeps the controller query state synchronized through focus changes and scrolling in the virtualized table layout while surfacing the active match count and a clear-search action inline
• the table layout now applies base-level and per-view summary config in a footer row, backed by a focused summary-resolution helper test, and the shared width map now keeps headers and body cells aligned on first render while the trailing visible column absorbs spare horizontal room; active column resizing now keeps the virtualized header and body cells in lockstep while widths shrink or grow, the sticky header background strip now matches the rendered header height, the first row starts directly beneath that header without an extra spacer gap, the first visible row now renders a top border so that junction reads as the header’s bottom edge, table headers now use a visible full-cell hover background only for non-active columns while focused headers keep a stable active background without the old sorted-column ring treatment or the extra header focus shadow, active table searches now keep a sticky in-table query strip while the panel is closed and stay synchronized with the virtualized row body when the filtered result set shrinks or the previous scroll position would otherwise leave stale row indexes behind, and grouped table views render full-width section rows for the active group key with a sticky section label beneath the table header instead of staying flat
• list, cards, and the map fallback now also expose configured summaries through a compact summary strip
• the property editor now surfaces base-level and per-view summary selectors so configured summaries are no longer edit-only in raw .base JSON
• the sort popover now includes a groupBy picker with direction controls above the sort list, and the popover itself scrolls when vertical space is constrained so those controls stay contained within the panel

The remaining parity work is still substantial, but the repo now has an executable checklist and less type/config duplication between @lapis-notes/api and plugin-bases.

Current implementation

Shared API

packages/api/src/lib/bases.ts currently exports the public Bases compatibility layer used by first-party plugins and parity tests. It includes:

• core identifiers and config types such as BasesPropertyType, BasesPropertyId, BasesConfigFile, BasesViewConfig, and BasesViewRegistration
• Value wrappers such as BooleanValue, NumberValue, StringValue, DateValue, DurationValue, FileValue, ListValue, and ObjectValue
• query result helpers such as BasesEntry, BasesEntryGroup, BasesQueryResult, QueryController, parsePropertyId, and toValue

This file is useful as a compatibility surface, and it now owns more of the shared value/config behavior than it did during the initial audit. It is still not the complete source of truth for the running Bases feature, because runtime query execution and view/controller behavior remain plugin-local.

Runtime plugin

packages/plugins/plugin-bases/src/ contains the working Bases feature. Today it provides:

• a BasesPlugin that registers .base and .bases files to the bases view type
• a BasesView file view that supports source and preview modes
• built-in table, cards, list, map, and fallback unknown renderers
• a query controller that builds rows from metadataCache, frontmatter, and a PEaQL-backed in-memory table
• toolbar actions for view selection, limit, sort, group, filters, search, CSV export/copy, note creation, and property visibility/formulas/summaries

The runtime supports:

• global filters and per-view filters
• formula columns
• base-level and per-view summaries
• grouped result derivation from groupBy
• sort order
• row limits
• search across displayed properties
• frontmatter-backed note properties
• toolbar create/copy/export workflows
• a small set of file-derived columns such as file.name, file.path, file.folder, file.ext, file.ctime, file.mtime, file.size, and file.tags

Internal duplication

The plugin also carries a second, private Bases runtime model in packages/plugins/plugin-bases/src/bases-view/bases.svelte.ts.

Some of the duplication identified in the original audit has now been reduced:

• DateValue and DurationValue helper behavior has been moved into the shared API
• shared BasesViewConfig and shared option types are now used by the plugin’s view configuration surface

The remaining private model still owns the runtime-specific pieces, especially:

• QueryController
• the plugin-local BasesView base class
• the running query/result lifecycle

Because the plugin and shared API evolve independently, parity work done in one layer does not automatically reach the other.

Confirmed parity gaps

1. Shared API type drift from upstream

The shared API does not currently match the upstream Bases types closely enough to claim parity.

Confirmed drift includes:

• BasesPropertyId is declared as string | ... locally, while upstream requires a prefixed form ${BasesPropertyType}.${string}
• BasesConfigFile now includes upstream-style formulas and summaries, and the runtime executes more of that config than it did initially, but not with full upstream semantics
• BasesConfigFileFilter is currently a broad Record<string, unknown> instead of the recursive upstream union of string | { and } | { or } | { not }
• BasesConfigFileView now includes groupBy and summaries, and the runtime uses both fields, but grouped-view and summary behavior is still narrower than upstream
• option interfaces have been expanded to cover fields such as placeholder, filter, instant, and shouldHide, but view/config semantics are still incomplete in the runtime
• BasesOptionGroup and BasesViewRegistration.options now match the upstream grouped-options and callback shape more closely
• BasesView.createFileForView() is now implemented in the shared API and surfaced in the plugin toolbar, but the public API still does not drive the full runtime directly
• BasesViewConfig.getEvaluatedFormula() is a stub that wraps raw config values instead of evaluating a formula in Bases context

2. Runtime config semantics are narrower than Obsidian Bases

The current plugin runtime only implements a subset of the documented Bases config model.

Confirmed gaps include:

• the runtime now groups groupedData when groupBy is present in the view config, and the toolbar can edit that config; the list, cards, and table layouts now render grouped sections explicitly, but other grouped-view semantics are still narrower than upstream
• no evidence that this context is supported the way the docs describe for opened, embedded, and sidebar Bases

The runtime query generator currently applies formulas, filters, sort, limit, grouped result derivation, and summary aggregation, but not the broader grouped-view workflows or this semantics that Obsidian exposes.

3. Built-in view coverage is incomplete

Obsidian help documents four built-in view layouts:

• table
• cards
• list
• map

The current plugin now registers:

• table
• cards
• list
• map
• unknown

For map, the upstream product also depends on the Maps plugin. The local runtime now provides an explicit fallback state for that layout name, but it still does not implement a real map-capable renderer.

4. Toolbar and workflow coverage is incomplete

Obsidian’s help pages document a broader toolbar and workflow surface than the current plugin provides.

Currently present:

• view selection and editing
• limit
• sort
• filter
• property visibility and formula editing
• search over displayed properties through a toggleable panel above the active view
• base-level and per-view summary editing for the selected property
• group configuration editing

Documented but currently missing or not surfaced in the plugin:

• no additional toolbar/workflow gaps are currently called out by this audit beyond the remaining layout/semantic differences below

5. File property coverage is incomplete

The docs describe a broader file-property surface than the plugin currently provides. Verified local coverage today is limited to:

• file
• file.file
• file.name
• file.basename
• file.fullname
• file.path
• file.folder
• file.ext
• file.ctime
• file.mtime
• file.size
• file.tags
• file.links
• file.embeds
• file.backlinks
• file.properties

The documented file-property names are now exposed in the runtime. Some related helpers such as hasLink() and hasProperty() exist, but richer file-value semantics are still missing.

6. Formula function coverage is partial

Verified local function coverage comes from two places:

• explicit Bases registrations in plugin-bases/src/bases-view/functions.ts
• generic PEaQL functions in node_modules/peaql/src/lib/query/query_env.ts

Verified function names available today:

• local Bases-specific: isEmpty, isTruthy, toString, startsWith, endsWith, contains, containsAny, containsAll, containsAnyOf, containsAllOf, inFolder, hasLink, hasTag, hasProperty, length, map, filter, reduce, icon, title, relative, time, trim, split, replace, repeat, reverse, slice, ceil, floor, list, number, max, min, random, flat, join, sort, unique, escapeHTML, date, duration, file, html, image, link, if, isType, asFile, asLink, linksTo, keys, values, matches
• PEaQL-provided names that overlap partially with Bases docs: abs, round, toFixed, today, now, format, lower

The remaining function parity gaps are now mostly about value-model depth and method-style semantics rather than missing registered function names.

Documented method-style functions that are missing, only partially present, or exposed under different names:

• any: thin isTruthy, toString, and isType helpers are now registered, but the broader method-style value API is still incomplete
• date: date(), format(), time(), relative() as date methods rather than only ad hoc helpers
• string: method-style dispatch still needs broader runtime coverage beyond the newly registered names
• number: method-style dispatch still needs broader runtime coverage beyond ceil and floor
• list: method-style dispatch semantics still need deeper runtime coverage even though the helper names are now registered
• link: asFile and linksTo are now registered as thin helpers, but richer link-value semantics are still missing
• file: asLink is now registered as a thin helper, but richer file-value semantics are still missing
• object: broader value-model integration still needed beyond keys and values
• regexp: broader value-model integration still needed beyond matches

There is also naming drift from the docs:

• docs use containsAny and containsAll
• the runtime now exposes both the upstream names and the older local aliases containsAnyOf and containsAllOf

That reduces one compatibility gap, but formula compatibility is still not aligned with Obsidian’s public Bases language overall.

7. Value-model parity is incomplete

The shared API exports some upstream value classes by name, but behavior is incomplete.

Examples:

• shared DateValue and DurationValue now expose the core helper methods that were called out in the original audit, but other value wrappers remain thin
• shared LinkValue, HTMLValue, IconValue, ImageValue, TagValue, UrlValue, and RegExpValue are still mostly marker subclasses without upstream behavior
• the private plugin model still owns runtime-specific view/controller behavior that is not shared through @lapis-notes/api

8. Parity reporting is more optimistic than the actual implementation

packages/api/scripts/generate-obsidian-parity.mjs marks many Bases symbols as implemented through explicit overrides. The generated parity fixture therefore reports name-level coverage, but it does not validate:

• type accuracy
• method completeness
• runtime semantics
• formula language compatibility
• UI workflow parity

The current parity report is useful as an inventory, but not as proof of working Bases parity.

Plan to attain parity

1. Make @lapis-notes/api the single source of truth for Bases types and values

Unify the duplicated Bases model so the plugin consumes the same public implementation that the rest of the repo imports.

Work items:

• move the richer private value and config types out of plugin-bases and into packages/api/src/lib/bases.ts
• update plugin-bases to import those shared types instead of maintaining a parallel copy
• align all exported types and method signatures to upstream obsidian.d.ts unless the repo intentionally documents a divergence

2. Close the shared API type gaps first

Before adding more UI behavior, the public API should match the upstream Bases contract closely.

Work items:

• correct BasesPropertyId, BasesConfigFile, BasesConfigFileFilter, BasesConfigFileView, and option interfaces
• finish aligning the remaining upstream fields and semantics such as stricter filter typing, placeholder, filter, instant, and shouldHide
• update BasesViewRegistration.options to the upstream callback signature
• implement BasesViewConfig.getEvaluatedFormula() rather than leaving it as a stub

3. Implement the documented Bases value model and function surface

Formula compatibility depends on both type wrappers and function dispatch.

Work items:

• finish the value wrappers for DateValue, DurationValue, LinkValue, HTMLValue, ImageValue, IconValue, FileValue, ListValue, ObjectValue, and RegExpValue
• add the documented global and method-style Bases functions under the upstream names
• add compatibility aliases only where needed, but prefer Obsidian’s names over local variants
• explicitly map or wrap PEaQL helpers so formula authors can use Obsidian syntax instead of query-engine internals
• add tests for every documented function name and for key return-type/rendering behavior

4. Expand the query engine to match Bases semantics

The runtime currently handles formula projection, filtering, sorting, and limit. It needs the rest of the documented Bases execution model.

Work items:

• deepen grouped-view rendering beyond the current list, cards, and table grouped sections
• implement custom summary formulas beyond the current keyed aggregate support
• add this binding semantics for opened, embedded, and sidebar Bases
• support the documented file-property fields such as backlinks, links, embeds, and properties with clear refresh behavior

5. Bring the built-in views and toolbar up to documented coverage

Once the shared model and query runtime are aligned, the UI should match the documented Bases workflows.

Work items:

• design a map view strategy that can either integrate with a future map capability or fail explicitly behind capability detection
• extend grouped rendering and richer grouped workflows to cards, table, and any eventual map implementation

6. Replace name-level parity overrides with executable parity checks

The current parity fixture should become a starting point, not the success criterion.

Work items:

• keep the symbol inventory, but stop treating explicit overrides as proof of parity
• add shared API tests that validate signatures and observable behavior for Bases-specific classes
• add plugin-level tests that exercise .base parsing, formulas, filters, summaries, grouping, and view registration
• add function-coverage tests that compare the documented Bases function list against the registered/effective runtime function list

Recommended delivery order

To reduce churn, parity work should land in this order:

1. Continue unifying the shared API and plugin-private Bases model, starting with the remaining runtime classes instead of recreating more config/value shims locally.
2. Align config and value types with upstream obsidian.d.ts.
3. Add missing function names and value behaviors with exhaustive tests.
4. Deepen method-style value behavior, grouped rendering, this, and missing file semantics.
5. Finish the remaining built-in view behavior, especially real map capability and non-list grouped layouts.
6. Add map view only after the runtime has a clear map-capability story.
7. Tighten parity tooling so future audits measure behavior, not just symbol presence.

Current parity status

Current status can be summarized as follows:

• shared API parity: partial and type-shim heavy
• runtime query parity: partial but broader than the initial audit
• documented function parity: partial but largely name-complete
• built-in view parity: near-complete on layout names, incomplete on grouped behavior and map capability
• toolbar/workflow parity: broad for the documented day-to-day controls
• parity reporting fidelity: optimistic

The repository is far enough along to support basic Bases workflows, but it should not yet be considered at parity with upstream Obsidian Bases.

Canvas Plugin (@lapis-notes/canvas)

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

Manifest: id lapis-canvas, version 0.0.1, min app version 1.7.7.

The canvas package owns external official JSON Canvas editing for .canvas files. The package remains in the monorepo for building official release artifacts, but the workspace no longer bundles or registers it by default.

Runtime Surface

• View type: canvas.
• Extensions: .canvas.
• Command: create-new-canvas.
• Official registry identity: lapis-canvas.
• Install location: /.obsidian/plugins/lapis-canvas; listed under Core plugins when installed provenance is official.
• Package exports: plugin runtime entry at @lapis-notes/canvas, read-only embed helpers at @lapis-notes/canvas/embed, and standalone stylesheet artifact at @lapis-notes/canvas/styles.css.

Key Behaviors

• Parses JSON Canvas documents into Svelte Flow nodes and edges.
• Serializes edits back into JSON Canvas after changes.
• Supports creating, editing, resizing, coloring, and connecting text, link, file, and group nodes, including containment-driven group membership that moves contained nodes with the group, adopts dragged-in nodes, releases dragged-out nodes, and leaves contained nodes in place when the group is deleted.
• Renders whole-file markdown file nodes through the markdown package’s editable inline markdown surface, while markdown subpath targets and non-markdown file nodes reuse the markdown package’s read-only file-embed rendering path.
• Shows file-node filenames in a badge anchored over the node’s top-left border so the file identity stays visible even when the body is an embedded renderer.
• Leaves embedded markdown and file-preview surfaces inert until the node is selected, so wheel and pointer gestures keep panning the canvas for unselected nodes.
• Suppresses per-node action toolbars during multi-node selections and renders one shared bulk toolbar above the selection bounds for actions that apply to the whole selection, including grouping the selection into a newly selected group with immediate label editing, delete, recolor, and zoom.
• Renders group labels as top-right badge inputs that keep a larger minimum edit size around mid-to-low zoom, use the available badge width instead of shrink-wrapping to the text, and choose black or white text from the computed group-badge background brightness so saturated accents like purple stay readable.
• Renders JSON Canvas palette colors as tinted node surfaces and maps directional connectors onto compact filled edge markers that stay visible without explicit connector colors.
• Thickens hovered connectors to the selected stroke width and glow, keeps visible connector labels on normal zoom scaling as padded label chips that mask the line beneath them, routes connectors as curved paths with short straight exit segments from node sides before the bezier span begins, renders the inline connector label editor as a CSS-sized contenteditable surface with a larger minimum edit size at small zoom, and exposes edge-toolbar actions to edit or remove existing connector labels.
• Switches text and file nodes into low-detail previews below zoom 0.3, showing skeleton placeholders for text nodes and centered filename pills for file nodes while leaving group headers and edge labels on their normal zoom scaling path.
• Keeps connector handles hidden at rest while their edge anchors still sit on the node boundary, and reveals each side only when its matching resize control is hovered or focused while still exposing connection-state indicators during active drags.
• Shows valid target handles as visible indicators during connector drags and ignores duplicate identical connect emissions so one drag persists only one edge.
• Styles the drag-selection overlay with the interactive accent token for both its border and translucent fill.
• Uses empty-space drag as the default box-selection gesture and switches that drag gesture back to viewport panning while the Space key is held.
• Uses wheel scrolling to pan the canvas viewport by default, while ctrl-wheel zooms the viewport, with an explicit minimum zoom of 0.03.
• Renders group nodes as lower-layer container surfaces.
• Clips the interactive canvas surface to the active pane.
• Creates new empty canvas files at the vault root.
• Persists debounced canvas edits through the vault.
• Exports a read-only CanvasEmbed surface plus JSON Canvas parsing, serialization, flow-conversion, and color helper utilities so external hosts can render supplied canvas data without file-backed view lifecycle or save behavior.
• Registers .canvas with the markdown embed registry so markdown reading mode and live preview render canvas file embeds through the same read-only surface instead of falling back to raw text.
• The first embed slice intentionally stays read-only and data-driven: it renders supplied text, file, link, and group nodes without the editable canvas node toolbars, drag/resize controls, or vault-backed file preview lifecycle used by the full plugin view.
• Hosts may optionally provide explicit file-content previews to CanvasEmbed so file nodes render richer markdown bodies while still staying read-only and vault-independent.
• Read-only embeds keep connector arrows and passive connector labels visible, and overflowing text/file preview content scrolls inside the node body instead of expanding the host frame.

CSS Ownership

The package injects Svelte Flow and canvas styling at plugin load time, uses canvas-... namespaced selectors, and should remain aligned with the shared Plugin CSS Contract as first-party CSS ownership evolves.

CSV Plugin (@lapis-notes/csv)

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

Package: @lapis-notes/csv. Manifest id: csv.

The CSV package owns bundled CSV and TSV editing with rainbow source highlighting and an editable table preview.

Registration

• View type: csv
• Core-plugin activation through the workspace shell
• File associations: .csv, .tsv
• Language-service provider: csv-lint (in-plugin, diagnostics for csv and tsv)

Current Functionality

• Ships the first-party plugin package and manifest for bundled CSV support.
• Registers a dedicated file-backed CSV leaf instead of falling back to a generic text editor.
• Opens .csv and .tsv files in a dual-mode view: table preview (default) and rainbow-highlighted source.
• Uses a vendored Lezer grammar adapted from codemirror-lang-csv for rainbow column highlighting in source mode.
• Parses and serializes CSV text through Papa Parse with a mutable CsvGrid model for table preview edits.
• Syncs preview and source through the shared text Editor instance attached to the leaf.
• Renders the table preview with @lapis-notes/ui/table, sticky headers, optional 1-based # row numbers, rainbow column tinting in preview, border-positioned row/column grips (column grip on the header top border), rectangle multi-cell selection, @dnd-kit/svelte row/column drag reorder with a custom DragOverlay preview of the full row or column, a 5px pointer-move activation threshold on grips so click-to-select stays distinct from drag-to-reorder, accent drop indicators, and in-table source fading while dragging, context menus for clear/delete cells plus row/column actions, editable headers with automatic header-row promotion, column move menu actions, and markdown-inspired --interactive-accent selection chrome. Header column menus are absolutely positioned so selection borders align with body cells. Row drag uses a single draggable on the first body cell grip with row droppables on every body cell. Playwright coverage in packages/workspace/e2e/csv-editor.spec.ts includes grip click selection, column grip drag reorder, multi-cell drag-select, row reorder via the context-menu Move row down action, and computed-style checks that selected cells render the accent fill (--table-selection) and border (--interactive-accent) overlay.
• Wires preview-mode undo/redo (Mod+Z, Mod+Shift+Z, Mod+Y) through a view scope while deferring to native input undo during active cell edits.
• Marks preview serialization edits as CodeMirror user events so shared editor history groups sensibly.
• Skips CodeMirror lint diagnostics in table preview mode; CSVLint runs only in source mode to avoid redundant parse work during table edits.
• Registers an in-plugin CSVLint-inspired language-service provider (csv/field-count, csv/quote-consistency, csv/parse-error) with line-bounded diagnostic ranges and a document-size guard; surfaced in source mode through shared lint gutter/inline UI.
• Shows Papa Parse errors in the table preview banner without re-parsing on programmatic editor sync echoes.
• Persists plugin settings (header row, delimiter override, row numbers) through bundled plugin data.
• Emits dist/app.css for workspace loading and dist/styles.css for standalone/plugin-local CSS consumption.
• Namespaces plugin-owned chrome under csv-... selectors and maps colors through --csv-... theme variables.

E2E Vault Fixtures

Tracked under e2e-vault/plugin-csv/:

• CSV Feature Tour.md — manual verification guide
• assets/valid-basic.csv — table preview baseline
• assets/valid-quoted-multiline.csv — quoted commas and multiline cells
• assets/valid-sample.tsv — tab-delimited sample
• assets/lint-ragged-columns.csv — ragged row lint fixture
• assets/lint-quote-mismatch.csv — broken quoting lint fixture

Package Boundary

The plugin owns CSV-specific file views, parsing, table preview UI, CSV lint registration, and CodeMirror language support. Generic file-view lifecycle, plugin activation, shared lint UI, and vault I/O remain in @lapis-notes/api and the workspace shell.

Related Contracts

• Plugin Runtime
• Editor Rendering and Views
• Language Services

Docs Plugin (@lapis-notes/docs)

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

Manifest: id lapis-docs, version 0.1.0, min app version 0.20.0.

The docs package owns Univer-backed editing for native .lapisdoc and .lapissheet files. It ships as the official installable lapis-docs registry plugin instead of through the bundled workspace bootstrap.

Runtime Surface

• View types: docs-document, docs-sheet.
• Extensions: .lapisdoc, .lapissheet.
• Commands: lapis-docs:create-document, lapis-docs:create-sheet.
• Package exports: plugin runtime entry at @lapis-notes/docs, app stylesheet at @lapis-notes/docs/app.css, and standalone stylesheet artifact at @lapis-notes/docs/styles.css.
• Official registry entry: lapis-docs in the locked lapis-official source, advertising .lapisdoc and .lapissheet editor-view contributions.

File Format

Both native file types store plain JSON wrappers in the vault:

{
  "kind": "univer-doc | univer-sheet",
  "version": 1,
  "snapshot": {},
  "meta": {}
}

• kind selects the matching Univer runtime and view.
• version gates future migrations.
• snapshot preserves Univer-owned document or workbook state without normalizing its schema inside Lapis.
• meta is optional provenance space for future import/export workflows.

Key Behaviors

• Registers dedicated editor views for .lapisdoc and .lapissheet after the official lapis-docs plugin is installed and enabled. Before installation, the workspace on-demand install prompt can offer Install and open from the signed official registry contribution summary.
• Parses native snapshot wrappers, rejects malformed JSON and wrong file kinds, and shows explicit in-view error states instead of falling back to raw text.
• Bootstraps Univer Docs and Sheets lazily through the documented @univerjs/presets createUniver() entry point, with directly composed OSS Univer plugin lists for each editor type. The runtime keeps preset CSS and locale assets but avoids preset JS facade side effects that register sheet-only observers against document sessions.
• Waits for the mounted editor pane to have usable dimensions before creating Univer, so sheets do not initialize against zero-width panes.
• Keeps the Univer runtime lazy-loaded, but browser builds must still load the runtime dependency shim before Univer so async-lock, React, and related CommonJS dependencies initialize without ESM interop failures.
• Mirrors the app light/dark state into Univer and bridges app theme tokens into the embedded surface so sheet borders, buttons, and other chrome remain visible under the workspace design system.
• Persists snapshot changes back to the vault as debounced JSON writes and surfaces save failures with reload and retry actions.
• Creates new native document and sheet files at the vault root through plugin-scoped commands.
• Seeds the demo vault with representative .lapisdoc and .lapissheet fixtures that render visible document and sheet content for smoke verification and workspace e2e coverage.
• Workspace e2e coverage verifies editor readiness and rendered Univer output, not only shell mount, and fails on unexpected page errors or console warnings/errors from the docs runtime.

Deferred Scope

• .lapisslide is reserved conceptually but not registered because Univer Slides is still outside the repo’s production-ready target.
• .xlsx, .docx, .pptx, .csv, and .tsv remain out of scope for this plugin. CSV/TSV stays with the CSV plugin, and Office exchange work remains a future server-backed follow-up.
• Existing vaults that have data under the old bundled docs ID are migrated by the workspace startup path by copying that data to lapis-docs when the new target ID has no data yet. The source docs data is preserved during this release.

CSS Ownership

The package ships a standalone stylesheet artifact that combines Univer preset CSS with package-local shell styling. Registry installation stores that styles.css artifact under /.obsidian/plugins/lapis-docs/, and the plugin manager injects it when the installed plugin is enabled. Package selectors stay under the docs-view__ namespace and follow the shared Plugin CSS Contract.

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.

Graph Plugin (@lapis-notes/graph)