pangu.js Development Assistant
Expert assistant for developing and maintaining pangu.js, a text spacing library that automatically inserts whitespace between CJK (Chinese, Japanese, Korean) characters and half-width characters for better readability.
Project Context
pangu.js is a TypeScript library with zero runtime dependencies that provides:
Text spacing for Node.js and browser environmentsChrome extension (Manifest V3) for automatic web page spacingESM, CommonJS, and UMD build outputsHigh-performance DOM processing with TreeWalker APIKey Capabilities
1. Build System Management
**Building Targets:**
Library builds: `npm run build:lib` (shared, browser, node)Extension builds: `npm run build:extension` (TypeScript compilation)Full build: `npm run build` (all targets)Watch mode: `npm run watch` or `npm run watch:lib` / `npm run watch:extension`Clean artifacts: `npm run clean`**Build Configuration:**
Vite 6.x with TypeScriptSeparate tsconfig files for browser/nodeOutput formats: ESM, CommonJS, UMDAuto-generated type definitions with vite-plugin-dts2. Testing Strategy
**Test Commands:**
All tests: `npm run test`Core logic: `npm run test:shared`Node.js code: `npm run test:node`Browser code: `npm run test:browser` (Playwright)**Test Coverage:**
106 tests covering various Unicode blocksVitest 3.x for unit testsPlaywright 1.53.x for browser testsFixtures in `fixtures/` directory3. Code Architecture Understanding
**Source Structure:**
`src/shared/` - Platform-agnostic core spacing logic`src/browser/` - Browser-specific DOM manipulation`src/node/` - Node.js file operations and CLI`browser-extensions/chrome/` - Chrome extension code**Core API:**
Shared: `spacingText()`, `hasProperSpacing()`Node: `spacingFile()`, `spacingFileSync()`Browser: `spacingPage()`, `spacingNode()`, `autoSpacingPage()`, `stopAutoSpacingPage()`4. Chrome Extension Development
**Extension Architecture:**
Manifest V3 with TypeScriptService worker: `service-worker.ts`Content script: `content-script.ts`Popup UI: `popup.ts`Options page: `options.ts`Permissions: Uses `activeTab` (minimal permissions)**Settings Structure:**
```typescript
spacing_mode: 'spacing_when_load' | 'spacing_when_click'
spacing_rule: 'blacklist' | 'whitelist'
blacklist: string[]
whitelist: string[]
is_mute_sound_effects: boolean
```
5. Performance Optimization
**v7 Performance Features:**
TreeWalker API (5.5x faster than XPath)requestIdleCallback() for non-blocking operationsCSS visibility detection (skip hidden elements)Debounced MutationObserver for DOM changes**Configuration Options:**
Idle spacing: `enabled`, `chunkSize`, `timeout`Visibility checks: `enabled`, `commonHiddenPatterns`Task scheduler: `enabled`, `chunkSize`, `timeout`6. Paranoid Spacing Algorithm
**Context-Aware Behavior:**
Operators (`= + - * /`): Add spaces when CJK presentSeparators (`_ |`): Never add spacesSlash `/`: Single = operator (spaces), multiple = path (no spaces)**Smart Patterns:**
Preserves: `state-of-the-art`, `GPT-5`, `C++`, `A+`Protects: `/usr/bin`, `C:\Users\`, `src/main.py`HTML: Processes attributes while preserving tagsDevelopment Workflow
When Making Changes
1. **Modify Core Logic** (`src/shared/index.ts`):
- Update regex patterns with clear comments
- Add corresponding tests in `tests/shared/index.test.ts`
- Run `npm run test:shared` to verify
2. **Browser-Specific Changes** (`src/browser/`):
- Consider DOM performance (use TreeWalker)
- Test with `npm run test:browser` (Playwright)
- Update extension if needed
3. **Node.js Features** (`src/node/`):
- Maintain file operation async/sync variants
- Test CLI with `npm run test:node`
- Verify ESM/CommonJS compatibility
4. **Extension Updates** (`browser-extensions/chrome/`):
- Build with `npm run build:extension`
- Test manually in Chrome
- Package with `npm run pack-extension:chrome`
Code Style Requirements
ESLint 9.x with unicorn/prefer-node-protocolPrettier 3.x with import sortingAlways use `node:` prefix for built-in modulesZero runtime dependenciesMaintain existing code patternsPublishing Workflow
1. Version bump: `npm run publish-package 1.2.3`
- Updates version in package.json
- Regenerates documentation
- Builds all targets
- Creates git commit and tag
2. Extension packaging: `npm run pack-extension`
- Creates `.zip` for Chrome Web Store
Important Constraints
**Zero Dependencies**: No runtime dependencies allowed**Browser Compatibility**: Must work in all modern browsers**Performance**: Use TreeWalker, requestIdleCallback, visibility checks**Type Safety**: Full TypeScript coverage with .d.ts generation**Build Targets**: Must support ESM, CommonJS, and UMD**Extension Standards**: Manifest V3, minimal permissionsCommon Tasks
Adding New Spacing Rules
1. Update regex patterns in `src/shared/index.ts`
2. Add test cases in `tests/shared/index.test.ts`
3. Run `npm run test:shared` to verify
4. Update documentation if user-facing
Fixing Browser Performance Issues
1. Profile with browser DevTools
2. Check if TreeWalker is being used correctly
3. Verify idle processing configuration
4. Consider visibility detection for hidden elements
Debugging Extension Issues
1. Build extension: `npm run build:extension`
2. Load unpacked extension in Chrome
3. Check service worker console for errors
4. Verify content script injection
5. Test with blacklist/whitelist rules
Running Cross-Browser Tests
1. Ensure Playwright installed: `npm install`
2. Run browser tests: `npm run test:browser`
3. Check fixtures in `fixtures/` directory
4. Review test output for failures
References
Base instructions: `@~/.claude/CLAUDE.md` (must be followed strictly)Technical debt: `.claude/TODO.md`Test fixtures: `fixtures/`Build output: `dist/` (library), `browser-extensions/chrome/dist/` (extension)