[docs/ui] Document plugin module loading and expose diagnostics #223

New issue

Closed

opened 2026-06-02 09:43:43 +00:00 by steve · 0 comments

steve commented

2026-06-02 09:43:43 +00:00

Owner

Problem

Plugin authors and users need clear documentation and UI diagnostics for module format selection, shared dependencies, fallback behavior, and plugin asset URL modes.

Goal

Document ESM/CommonJS plugin module loading and expose runtime diagnostics in plugin management UI.

Scope

Add developer docs for ESM plugins, CommonJS compatibility, shared host modules, and module loading architecture.
Document how to declare shared dependencies, what must be bundled, how ESM updates/reload work, and why sidecar has a smaller dependency surface.
Add Plugins UI badges for ESM, CommonJS compatibility, hybrid, sidecar, fallback used, missing dependency, deprecated host API, and reload required.
Add plugin detail diagnostics for selected host, format, entry, fallback, shared dependencies, missing or deprecated dependencies, asset URL mode, and version/hash URL.

Non-goals

Do not create new plugin runtime behavior solely for documentation.
Do not document arbitrary plugin-defined import maps as supported in v1.
Do not present deprecated/private host modules as stable APIs.

Acceptance Criteria

Plugin authors can build a valid ESM-first plugin from docs.
Users can see why a plugin loaded through fallback or failed dependency checks.
Deprecated/private host API usage is visible before it becomes a hard failure.

Implementation Notes

Keep docs aligned with generated host-module metadata and runtime selector behavior.
UI diagnostics should use concise labels with detail available in plugin detail panels.
Update relevant spec pages when functionality changes land.
Extend API community-plugin diagnostics with the remaining loader-facing fields: reload-required, fallback-used, asset URL mode/URL, deprecated shared dependencies, and private shared dependencies.
Render a concise loader badge row in the existing plugin Features panel for ESM, CommonJS compatibility, hybrid fallback, Electron sidecar, fallback used, missing dependency, deprecated host API, and reload required. Keep detailed values in the same Runtime Status section so settings search can index them.
Add developer-facing runtime docs under plugin-runtime.md and registry docs that explain ESM-first manifests, shared dependencies, bundling expectations, reload/update semantics, sidecar narrowing, asset URL shapes, and unsupported plugin-defined import maps.
Update workspace/API specs and focused tests for diagnostics propagation and feature-panel rendering.

Affected Packages and Files

packages/api/src/lib/plugin-manager.ts
packages/api/src/lib/plugin-runtime-entry.ts
packages/api/src/lib/__tests__/plugin-manager.test.ts
packages/api/spec.md
packages/workspace/src/lib/components/configuration/plugin-feature-sections.ts
packages/workspace/src/lib/components/configuration/community-plugins.ts
packages/workspace/src/lib/components/configuration/settings-search.ts
packages/workspace/src/lib/components/configuration/plugin-feature-sections.test.ts
packages/workspace/spec.md
spec/src/30-cross-package-contracts/plugin-runtime.md
spec/src/30-cross-package-contracts/plugin-registry.md
spec/src/20-packages/workspace/index.md
spec/src/20-packages/api/index.md

Suggested Files or Specs To Inspect

spec/src/30-cross-package-contracts/plugin-runtime.md
spec/src/30-cross-package-contracts/plugin-registry.md
spec/src/20-packages/workspace/index.md
packages/workspace/src/lib/components/settings/
packages/api/src/lib/plugin-manager.ts

Validation Commands

make spec-lint
mdbook build spec
pnpm --filter @lapis-notes/workspace check:all
pnpm check:all

Follow-up Tasks

Implementation Summary

Documented ESM-first plugin loading and registry expectations; extended community plugin diagnostics with fallback-used, reload-required, asset URL, and deprecated/private dependency fields; surfaced loader badges and details in plugin settings search/features UI.

## Problem Plugin authors and users need clear documentation and UI diagnostics for module format selection, shared dependencies, fallback behavior, and plugin asset URL modes. ## Goal Document ESM/CommonJS plugin module loading and expose runtime diagnostics in plugin management UI. ## Scope - Add developer docs for ESM plugins, CommonJS compatibility, shared host modules, and module loading architecture. - Document how to declare shared dependencies, what must be bundled, how ESM updates/reload work, and why sidecar has a smaller dependency surface. - Add Plugins UI badges for ESM, CommonJS compatibility, hybrid, sidecar, fallback used, missing dependency, deprecated host API, and reload required. - Add plugin detail diagnostics for selected host, format, entry, fallback, shared dependencies, missing or deprecated dependencies, asset URL mode, and version/hash URL. ## Non-goals - Do not create new plugin runtime behavior solely for documentation. - Do not document arbitrary plugin-defined import maps as supported in v1. - Do not present deprecated/private host modules as stable APIs. ## Acceptance Criteria - Plugin authors can build a valid ESM-first plugin from docs. - Users can see why a plugin loaded through fallback or failed dependency checks. - Deprecated/private host API usage is visible before it becomes a hard failure. ## Implementation Notes - Keep docs aligned with generated host-module metadata and runtime selector behavior. - UI diagnostics should use concise labels with detail available in plugin detail panels. - Update relevant spec pages when functionality changes land. - Extend API community-plugin diagnostics with the remaining loader-facing fields: reload-required, fallback-used, asset URL mode/URL, deprecated shared dependencies, and private shared dependencies. - Render a concise loader badge row in the existing plugin Features panel for ESM, CommonJS compatibility, hybrid fallback, Electron sidecar, fallback used, missing dependency, deprecated host API, and reload required. Keep detailed values in the same Runtime Status section so settings search can index them. - Add developer-facing runtime docs under `plugin-runtime.md` and registry docs that explain ESM-first manifests, shared dependencies, bundling expectations, reload/update semantics, sidecar narrowing, asset URL shapes, and unsupported plugin-defined import maps. - Update workspace/API specs and focused tests for diagnostics propagation and feature-panel rendering. ## Affected Packages and Files - `packages/api/src/lib/plugin-manager.ts` - `packages/api/src/lib/plugin-runtime-entry.ts` - `packages/api/src/lib/__tests__/plugin-manager.test.ts` - `packages/api/spec.md` - `packages/workspace/src/lib/components/configuration/plugin-feature-sections.ts` - `packages/workspace/src/lib/components/configuration/community-plugins.ts` - `packages/workspace/src/lib/components/configuration/settings-search.ts` - `packages/workspace/src/lib/components/configuration/plugin-feature-sections.test.ts` - `packages/workspace/spec.md` - `spec/src/30-cross-package-contracts/plugin-runtime.md` - `spec/src/30-cross-package-contracts/plugin-registry.md` - `spec/src/20-packages/workspace/index.md` - `spec/src/20-packages/api/index.md` ## Suggested Files or Specs To Inspect - `spec/src/30-cross-package-contracts/plugin-runtime.md` - `spec/src/30-cross-package-contracts/plugin-registry.md` - `spec/src/20-packages/workspace/index.md` - `packages/workspace/src/lib/components/settings/` - `packages/api/src/lib/plugin-manager.ts` ## Validation Commands - `make spec-lint` - `mdbook build spec` - `pnpm --filter @lapis-notes/workspace check:all` - `pnpm check:all` ## Related Issues ## Follow-up Tasks ## Implementation Summary Documented ESM-first plugin loading and registry expectations; extended community plugin diagnostics with fallback-used, reload-required, asset URL, and deprecated/private dependency fields; surfaced loader badges and details in plugin settings search/features UI.

steve added this to the Dual ESM/CJS plugin loader milestone

2026-06-02 09:43:43 +00:00

steve

2026-06-02 09:43:43 +00:00