200 Graph Background Particle Effects Plugin

[joesobo]

Summary

• Replace the first-pass CSS-gradient particle layer with a canvas renderer adapted from Odysseus' open-source static/js/theme.js effects.
• Move the particle renderer into a real workspace package: @codegraphy-dev/plugin-background-particles, with package metadata, codegraphy.json, README, changelog, build/typecheck/lint scripts, lockfile entry, and devhost/release-target coverage through workspace discovery.
• Align Graph Background presets with Odysseus' actual canvas patterns: Synapse, Rain, Constellations, Perlin Flow, Leaves (petals internally), Sparkles, and Embers.
• Make Leaves green, spawn/prewarm it from the left edge, and prewarm built-in effects so they do not start empty at the spawn point.
• Add custom particle effect support at the settings/runtime contract level: backgroundEffects.preset: "custom" plus backgroundEffects.customModule, loaded as a browser JS module exporting activateParticleEffect(context).
• Keep the effects persisted through backgroundEffects, normalize unsupported presets back to none, and render the canvas behind the Graph Stage without pointer interaction.

Custom Effects Note

• Custom particle modules are JavaScript files that run in the Graph View webview and export activateParticleEffect(context).
• The intended workspace convention is .codegraphy/particles/*.js; the package README and settings docs describe that contract.
• Remaining bridge work before calling custom effects fully end-user complete: resolve workspace-relative .codegraphy/particles/*.js paths into webview-safe module URLs during initial settings sync. The renderer already supports browser module URLs.

Source / License Note

• Particle routines are adapted from pewdiepie-archdaemon/odysseus, cloned locally at commit 9d7a3d6 for comparison.
• Odysseus is AGPL-3.0 licensed. This PR now contains an adapted derivative of that canvas code, so this needs an explicit license review before merging into the MIT CodeGraphy repo.

Stacking

• Current base: main.
• Earlier stack base was codex/191-graph-background-animation-theme / PR 191 Graph Background Animation Theme #266; PR 191 Graph Background Animation Theme #266 is merged, so this PR is no longer stacked.

Validation

• pnpm --filter @codegraphy-dev/plugin-background-particles run typecheck
• pnpm --filter @codegraphy-dev/plugin-background-particles run build
• pnpm --filter @codegraphy-dev/plugin-background-particles run lint
• pnpm --filter @codegraphy-dev/extension exec vitest run --config vitest.config.ts packages/extension/tests/extension/repoSettings/store/model/persistedShape/view.test.ts packages/extension/tests/extension/graphView/webview/settingsMessages/updates.test.ts packages/extension/tests/webview/legends/panel/view.test.tsx packages/extension/tests/webview/graph/viewport/tooltip.renderssurface2dfor2dmode.test.tsx
• pnpm --filter @codegraphy-dev/extension run typecheck
• pnpm --filter @codegraphy-dev/extension run build:webview
• pnpm --filter @codegraphy-dev/extension run lint (passes with existing generated acceptance spacing warnings)
• pnpm run test:release
• Pre-commit hook: acceptance spec guard, repo typecheck, lint-staged/eslint --fix
• Browser/canvas visual harness: bundled the package-owned startOdysseusBackgroundEffect module into /tmp/codegraphy-particle-harness, rendered all seven presets in Chromium headless, and captured /tmp/codegraphy-particle-harness/presets-package-full.png.

Trello: https://trello.com/c/TJgL2Yzq/200-design-a-graph-background-particle-effects-plugin

[changeset-bot]

🦋 Changeset detected

Latest commit: d2b9db1

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 12 packages

Name	Type
@codegraphy-dev/extension	Minor
@codegraphy-dev/plugin-api	Minor
@codegraphy-dev/plugin-particles	Minor
@codegraphy-dev/core	Patch
@codegraphy-dev/plugin-csharp	Patch
@codegraphy-dev/plugin-godot	Patch
@codegraphy-dev/plugin-markdown	Patch
@codegraphy-dev/plugin-python	Patch
@codegraphy-dev/plugin-svelte	Patch
@codegraphy-dev/plugin-typescript	Patch
@codegraphy-dev/plugin-vue	Patch
@codegraphy-dev/mcp	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR