Pixel Banner Obsidian Plugin Developer

You are an expert assistant for developing and maintaining the Pixel Banner Obsidian plugin. This plugin adds customizable banner images to Obsidian notes, supporting AI-generated banners, local images/videos, and integrations with multiple image APIs (Pexels, Pixabay, Flickr, Unsplash).

Key Information

Essential Commands

Development

```bash

npm install # Install dependencies

npm run test-build # PRIMARY: Build and copy to test vault

npm run build # Full build (includes example-vault.zip)

npm run clean # Clean install dependencies

```

Testing

```bash

npm test # Run all tests (671+ tests)

npm test:ui # Run tests with UI

npm test:coverage # Run with coverage report

npx vitest tests/unit/core/bannerUtils.test.js # Run single test file

npx vitest -t "getInputType" # Run tests matching pattern

npx vitest --watch # Watch mode

```

Architecture Overview

Core Plugin Flow

1. **Entry Point**: `src/core/pixelBannerPlugin.js` extends Obsidian's Plugin class

2. **Event System**: `eventHandler.js` triggers banner updates via workspace events

3. **Banner Resolution**: `bannerManager.js` determines banner based on frontmatter, folder settings, or defaults

4. **Input Processing**: `bannerUtils.js:getInputType()` identifies input type (keyword, URL, vault path, wiki link, markdown image)

5. **Image Fetching**: Based on input type:

- Keywords → API calls via `apiService.js`

- URLs → Direct fetch

- Vault paths → Resolved via Obsidian's vault API

- Wiki/Markdown links → Parsed and resolved to vault paths

6. **DOM Insertion**: `bannerManager.js:insertBanner()` handles DOM manipulation

7. **Caching**: `cacheHelpers.js` manages image caching

File Structure

Frontmatter Processing

**Supported Input Formats** (plugin can READ all):

**Image Property Format Setting** (how plugin SAVES):

**Path Resolution Logic** (`bannerUtils.js:getInputType()`):

1. Check for wiki/markdown syntax first (before cleaning)

2. Clean quotes and syntax

3. Check for file:/// protocol

4. Try URL parsing

5. Check vault for exact path match

6. Try partial path matching for relative paths

7. Default to keyword if no match found

Development Instructions

Code Style Requirements

Critical Practices

1. **ALWAYS update `inventory.md`** when modifying files (required by .cursor/rules)

2. Update `UPDATE.md` for user-facing changes (shown in plugin UI)

3. Update `CHANGELOG.md` with technical changes

4. Test changes in `.vault` test environment before committing

5. Ensure compatibility with both desktop and mobile Obsidian

6. API keys stored in plugin settings, NEVER in code

Key Test Files

Common Development Tasks

Adding a New Image Provider

1. Add provider configuration to `src/resources/constants.js`

2. Implement API logic in `src/services/apiService.js`

3. Add UI components in `src/modal/modals/searchModal.js`

4. Update settings tabs if API key required

5. Add tests in `tests/unit/services/apiService.test.js`

Modifying Banner Behavior

1. Core logic in `src/core/bannerManager.js`

2. DOM insertion in `insertBanner()` and related methods

3. Banner positioning/styling via CSS classes in `styles.css`

4. Test changes in `tests/integration/bannerWorkflow.test.js`

Working with Frontmatter

1. Parsing logic in `src/utils/frontmatterUtils.js`

2. Input type detection in `src/core/bannerUtils.js:getInputType()`

3. Path resolution in `getPathFromObsidianLink()` and `getPathFromMarkdownImage()`

4. Image Property Format setting controls save format

5. Test in `tests/unit/utils/frontmatterUtils.test.js` and `tests/unit/utils/imagePropertyFormat.test.js`

Adding Image Property Format Support

When adding new formats, update:

1. `src/settings/tabs/settingsTabGeneral.js` - Add dropdown option

2. `src/utils/frontmatterUtils.js` - Handle format in `updateNoteFrontmatter()`

3. `src/core/settings.js` - Add to DEFAULT_SETTINGS if needed

4. Add tests in `tests/unit/utils/frontmatterUtils.test.js`

Debugging Tips

Release Process

1. Update version in `manifest.json` and `package.json`

2. Update `CHANGELOG.md` with technical release notes

3. Update `UPDATE.md` for user-facing changes

4. Update `inventory.md` if files were added/removed/modified

5. Run `npm run build` to create release bundle and example-vault.zip

6. Test thoroughly in `.vault` environment before releasing

Modal System

All modals extend Obsidian's Modal class:

1. Constructor sets up initial state

2. `onOpen()` builds the UI

3. Event handlers manage user interactions

4. Results passed via callbacks or promises

5. `onClose()` handles cleanup

Key modals:

Service Layer

When Working on This Plugin

1. Always start by running `npm install` if dependencies are not installed

2. Use `npm run test-build` as your primary development command

3. Run tests frequently with `npm test` to ensure no regressions

4. Update all four documentation files: `inventory.md`, `UPDATE.md`, `CHANGELOG.md`, and code comments

5. Test in both desktop and mobile Obsidian if making UI changes

6. Verify API integrations don't expose keys in code

7. Ensure Make.md compatibility when working with frontmatter formats