Imported from stefmf/vault-pulse (AGENTS.md). Install upstream with npx skills add stefmf/vault-pulse. Copyright stays with the author.

Vault Pulse

Obsidian community plugin. GitHub-style activity heatmap rendered in a sidebar ItemView.

Quick reference

• Entry: src/main.ts → compiles to main.js
• Manifest id: vault-pulse (never rename — stable API for user data)
• Bundler: esbuild, target es2018, format cjs
• Tests: vitest with jsdom (npm test)
• Build: npm run build (typechecks + production bundle)

Module responsibilities

Conventions

• Pure functions in dateUtils, colorUtils, data, streakSymbols, i18n — testable without jsdom-on-obsidian.
• Plugin owns vault events — view subscribes ONLY to workspace.css-change. New vault-event sources go in main.ts and route through refreshAll().
• Render path is fingerprint-gated. Anything that would change what we draw belongs in view.computeRenderKey() so the short-circuit catches state changes correctly. Anything that changes which dates are in the grid belongs in view.computeStructureKey() so in-place updates fall back to a full rebuild when needed.
• DOM lifecycle via this.registerDomEvent, never window.addEventListener.
• Obsidian event lifecycle via this.registerEvent, never raw subscription.
• Frontmatter via metadataCache.getFileCache() only — never vault.read() (expensive, mobile-hostile).
• Quantile buckets only — never hardcoded count thresholds like count > 5 → level 4.
• CSS grid of <div> cells — never inline SVG. Icons go through setIcon (lucide).
• All user-facing text routes through t() — never inline English strings in view/settings code.
• Safe DOM writes only — containerEl.createDiv / createSpan / createEl for element creation (popout-window safe, inherits parent's window context). textContent / addClass / removeClass for mutation. Dynamic styles route through CSS variables via el.style.setProperty('--name', value) resolved by a class rule in styles.css — direct .style.x and setCssProps({ realProp: … }) are flagged by no-static-styles-assignment. innerHTML is forbidden. Reads off document use activeDocument instead.
• No backdrop-filter on persistent surfaces — it forces a compositor layer that bleeds across panes. Use color-mix(...) for translucency.
• Sentence case for every UI string — enforced by npm run lint:obsidian.
• Obsidian handles view teardown — do not call detachLeavesOfType in onunload.

Lint + test before push

npm run lint:obsidian   # ObsidianReviewBot rules (sentence case, no-static-styles, etc.)
npm test                # vitest suite
npm run build           # tsc + esbuild

Testing

npm test            # run once
npm run test:watch  # watch mode

Tests live under tests/ and alias the obsidian module to tests/__mocks__/obsidian.ts.

Release

Tag-triggered workflow at .github/workflows/release.yml. Pushing a semver tag (e.g. 0.1.0, not v0.1.0) builds and attaches main.js, manifest.json, styles.css as individual assets.

References

• Obsidian API: https://docs.obsidian.md
• Plugin guidelines: https://docs.obsidian.md/Plugins/Releasing/Plugin+guidelines
• Sample plugin: https://github.com/obsidianmd/obsidian-sample-plugin