P4RS3LT0NGV3/CONTRIBUTING.md

# Contributing to P4RS3LT0NGV3

Thank you for your interest in contributing! This guide will help you understand the project structure and how to add new features.

## 📁 Project Structure

Source layout (the runnable app is produced under **`dist/`** by `npm run build`; `dist/` is gitignored).

```
P4RS3LT0NGV3/
├── package.json
├── favicon.svg
├── index.template.html          # HTML shell; tool *script* tags updated by inject-tool-scripts
├── css/
│   ├── style.css
│   ├── themes-atmosphere.css    # Optional per-theme atmosphere / component overrides
│   └── notification.css
├── js/
│   ├── app.js                   # Vue app entry
│   ├── config/
│   │   └── constants.js
│   ├── core/                    # Shared logic (not tab-specific UI)
│   │   ├── decoder.js         # Universal decode engine
│   │   ├── steganography.js   # Emoji / invisible carriers
│   │   ├── toolRegistry.js    # Registers tools, merges Vue data/methods
│   │   └── transformOptions.js
│   ├── data/                    # Static data shipped with the app (see note below)
│   │   ├── anticlassifierPrompt.js
│   │   ├── emojiCompatibility.js
│   │   ├── endSequences.js
│   │   ├── glitchTokens.js
│   │   └── openrouterModels.js
│   ├── utils/
│   │   ├── clipboard.js
│   │   ├── emoji.js           # window.EmojiUtils (uses window.emojiData when present)
│   │   ├── escapeParser.js
│   │   ├── focus.js
│   │   ├── glitchTokens.js
│   │   ├── history.js
│   │   ├── notifications.js
│   │   ├── openrouterModels.js  # Fetch/cache OpenRouter model lists for Settings UI
│   │   └── theme.js             # Theme registry + applyTheme / cycleTheme
│   └── tools/                   # One *Tool.js per tab (extends Tool.js)
│       ├── Tool.js
│       ├── AntiClassifierTool.js
│       ├── BijectionTool.js
│       ├── DecodeTool.js
│       ├── EmojiTool.js
│       ├── GibberishTool.js
│       ├── MutationTool.js
│       ├── PromptCraftTool.js
│       ├── SplitterTool.js
│       ├── TokenadeTool.js
│       ├── TokenizerTool.js
│       ├── TransformTool.js
│       └── TranslateTool.js   # hidden tab wiring; UI lives on Transform
├── src/
│   ├── emojiWordMap.js          # Merged into generated emoji data at build time
│   └── transformers/            # Transformer sources → bundled to dist/js/bundles/
│       ├── BaseTransformer.js
│       ├── index.js             # Generated by npm run build:index (gitignored)
│       ├── case/
│       ├── cipher/
│       ├── concealment/
│       ├── encoding/
│       ├── format/
│       ├── signwriting/
│       ├── special/
│       ├── symbol/
│       ├── technical/
│       ├── unicode/
│       └── visual/
├── templates/                   # Injected into dist/index.html by inject-tool-templates
│   ├── anticlassifier.html
│   ├── bijection.html
│   ├── decoder.html
│   ├── fuzzer.html
│   ├── gibberish.html
│   ├── promptcraft.html
│   ├── splitter.html
│   ├── steganography.html
│   ├── tokenade.html
│   ├── tokenizer.html
│   ├── transforms.html
│   └── README.md
├── build/
│   ├── README.md
│   ├── build-index.js           # Writes src/transformers/index.js
│   ├── build-transforms.js      # Writes dist/js/bundles/transforms-bundle.js
│   ├── build-emoji-data.js      # Writes dist/js/data/emojiData.js
│   ├── copy-static.js           # Copies css/, js/, favicon → dist/
│   ├── fetch-glitch-data.js
│   ├── inject-tool-scripts.js   # Discovers tools; updates index.template.html + toolRegistry
│   ├── inject-tool-templates.js # Builds dist/index.html from index.template.html + templates/
│   ├── build-code-vendor.js     # Bundles QR/barcode libs → js/vendor/
│   └── build-alphabet-transforms.js  # Regenerates symbol/*.js from data/alphabets/
├── tests/
│   ├── test_universal.js
│   └── test_steganography_options.js
├── docs/
│   ├── TOOL-SYSTEM.md
│   ├── TOOL_ARCHITECTURE.md
│   ├── UI-COMPONENTS.md
│   └── THEMES.md                # Adding / editing themes
├── README.md
└── CONTRIBUTING.md

dist/   # npm run build — gitignored
├── index.html                   # `npm run build:templates` → from index.template.html + templates/
├── css/ …
├── js/ …
│   ├── bundles/transforms-bundle.js
│   └── data/emojiData.js
```

**Generated / ignored paths (also listed in `.gitignore`):** `dist/`, `src/transformers/index.js`, legacy `js/bundles/transforms-bundle.js`, `js/data/emojiData.js`, root `index.html` if present. The build updates **`dist/index.html`** only; a **root** `index.html` is not produced by the current scripts.

## 🎯 Key Concepts

### Core vs Tools

- **`js/core/`** — Shared business logic and infrastructure (not tab-specific)
  - Examples: `decoder.js` (DecodeTool, decoder pipeline), `steganography.js` (EmojiTool, steg engine), `toolRegistry.js` (registers tools, merges Vue surface), `transformOptions.js` (shared transform UI helpers)
- **`js/utils/`** — Cross-cutting helpers (`clipboard`, `EmojiUtils` in `emoji.js`, notifications, `theme.js`, `openrouterModels.js`, etc.)
- **`js/data/`** — Committed static payloads (models, prompts, glitch token data, end sequences, `emojiCompatibility.js`). **`emojiData.js`** is **not** edited here — it is **generated** to `dist/js/data/emojiData.js` by `npm run build:emoji`.
- **`src/`** — `emojiWordMap.js` feeds the emoji build; `transformers/` holds transformer modules
- **Generated bundle** — `npm run build:transforms` writes `dist/js/bundles/transforms-bundle.js` (a legacy `js/bundles/transforms-bundle.js` path may exist for older workflows and is gitignored)
- **`js/tools/`** — Vue integration: one `*Tool.js` per tab (plus `TranslateTool.js`, which is hidden and wired from the Transform tab)
  - Example: `DecodeTool.js` uses the universal decode API from `core/decoder.js`

### Transformers vs Tools

- **Transformers** (`src/transformers/`) - Text transformation logic (encoding/decoding)
- **Tools** (`js/tools/`) - UI features/tabs (Transform tab, Decoder tab, Emoji tab)

## 🚀 Getting Started

### Prerequisites

- Node.js (for running tests and builds)
- Modern web browser (for testing)

### Setup

```bash
# Clone the repository
git clone <repo-url>
cd P4RS3LT0NGV3

# Install dependencies (if any)
npm install

# Build transformers bundle
npm run build

# Run tests
npm test
```

## ✨ Adding New Features

### 1. Adding a New Transformer

Transformers are the core text transformation logic. See `src/transformers/README.md` for detailed instructions.

**Quick Start:**

1. Create a new file in the appropriate category directory:
   ```bash
   src/transformers/cipher/my-cipher.js
   ```

2. Use the `BaseTransformer` class:
   ```javascript
   import BaseTransformer from '../BaseTransformer.js';
   
   export default new BaseTransformer({
       name: 'My Cipher',
       priority: 60,              // See priority guide in transformers/README.md
       func: function(text) {
           // Encoding logic
           return encoded;
       },
       reverse: function(text) {
           // Decoding logic
           return decoded;
       },
       detector: function(text) {
           // Optional: pattern detection for universal decoder
           return /pattern/.test(text);
       }
   });
   ```

3. Rebuild the bundle:
   ```bash
   npm run build
   ```

4. Test it:
   - After `npm run build`, open **`dist/index.html`** in a browser (or use `npm start` → http://localhost:8080 if you prefer)
   - Your transformer will appear in the Transform tab automatically
   - Test encoding/decoding
   - Test with the Universal Decoder

5. Add tests (optional but recommended):
   - Add test cases to `tests/test_universal.js`
   - Run `npm test` to verify

6. Update documentation:
   - Add a bullet to the matching category under **Text Transformations** in the root `README.md`

**Important:** Transformers are automatically discovered and bundled. Category is set from the parent folder at build time — no manual registration needed.

### 2. Adding a New Tool (New Tab/Feature)

Tools represent UI features/tabs. Examples: Transform tab, Decoder tab, Emoji tab.

**Steps:**

1. Create a new tool class in `js/tools/`:
   ```javascript
   // js/tools/MyNewTool.js
   class MyNewTool extends Tool {
       constructor() {
           super({
               id: 'myfeature',        // Unique ID (used for tab switching)
               name: 'My Feature',     // Display name
               icon: 'fa-star',        // Font Awesome icon class
               title: 'My Feature (M)', // Tooltip with keyboard shortcut
               order: 5                // Display order (lower = earlier)
           });
       }
       
       getVueData() {
           return {
               // Vue data properties for this tool
               myInput: '',
               myOutput: ''
           };
       }
       
       getVueMethods() {
           return {
               // Vue methods for this tool
               doSomething: function() {
                   // Your logic here
               }
           };
       }
       
       getTabContentHTML() {
           return `
               <!-- HTML template for this tool's tab -->
               <div class="my-feature-layout">
                   <textarea v-model="myInput"></textarea>
                   <div>{{ myOutput }}</div>
               </div>
           `;
       }
   }
   ```

2. Run the build script to auto-register your tool:
   ```bash
   npm run build:tools
   ```
   
   This will:
   - Auto-discover your new tool file
   - Add script tag to `index.template.html`
   - Generate registration code in `toolRegistry.js`

3. If you created a template file, build templates:
   ```bash
   npm run build:templates
   ```

4. Test it:
   - After `npm run build`, open **`dist/index.html`** (or `npm start` at http://localhost:8080)
   - Your new tab should appear automatically
   - Test all functionality

**See `js/tools/Tool.js` for the base class API and `js/tools/TransformTool.js` for a complete example.**

### 3. Adding a New Utility Function

Utilities are shared helper functions used across the app. Currently, utility functions are typically added directly to the modules that need them or as part of core modules.

**If you need to create a new utility module:**

1. Create a new file in `js/` (root level) or `js/core/`:
   ```javascript
   // js/myUtility.js
   window.MyUtility = {
       doSomething: function(param) {
           // Your utility function
           return result;
       }
   };
   ```

2. Add a script tag to **`index.template.html`** (before `app.js`), then `npm run build:copy` (or `npm run build`) so it lands in **`dist/index.html`**:
   ```html
   <script src="js/myUtility.js"></script>
   ```

3. Use it in your code:
   ```javascript
   window.MyUtility.doSomething(value);
   ```

**Guidelines:**
- Keep utilities pure (no side effects when possible)
- Use `window` namespace for browser compatibility
- Document with JSDoc comments
- Consider adding to existing modules if functionality is related

**Note:** Prefer `js/utils/` for shared helpers (clipboard, emoji, escapeParser, focus, glitchTokens, history, notifications, theme, openrouterModels). Use `js/config/` for constants.

### 4. Adding or Updating a Theme

Themes are registry entries plus CSS token blocks—not Vue components.

1. Register the theme in `js/utils/theme.js` (`themes` array).
2. Add a `body.theme-<id> { … }` token block in `css/style.css` (copy from `body.theme-dark` or an existing custom theme).
3. Optionally add atmosphere rules in `css/themes-atmosphere.css`.
4. `npm run build`, then verify in the browser (dropdown, **`D`** cycle, nav, utility dock, toggles, mobile header utility button).

Full step-by-step guide, token checklist, and testing list: **[docs/THEMES.md](docs/THEMES.md)**.

## 🧪 Testing

### Running Tests

```bash
# Run all tests
npm test

# Run specific test suite
npm run test:universal      # Universal decoder tests
npm run test:steg           # Steganography options tests
```

### Writing Tests

- **Transformer tests**: Add to `tests/test_universal.js`
  - Tests are automatically discovered
  - Add limitations/expected behavior to the `limitations` object if needed
  
- **Steganography tests**: Add to `tests/test_steganography_options.js`
  - Tests encoding/decoding round-trips with various option combinations

- **New test files**: Create in `tests/` directory
  - Use `path.resolve(__dirname, '..')` to get project root
  - Use `path.join(projectRoot, '...')` for file paths

## 📝 Code Style

### JavaScript

- Use ES6+ features (arrow functions, const/let, template literals)
- Use meaningful variable names
- Add JSDoc comments for public functions
- Follow existing code style in the file you're editing

### File Organization

- **Core modules** (`js/core/`) — Shared logic (`decoder.js`, `steganography.js`, `toolRegistry.js`, `transformOptions.js`)
- **App entry** (`js/app.js`) — Vue bootstrap and shell behavior
- **Tools** (`js/tools/`) — Tab UI layer (`*Tool.js`)
- **Templates** (`templates/`) — Tool markup injected into `dist/index.html`
- **Transformers** (`src/transformers/`) — Transform implementations; output is `dist/js/bundles/transforms-bundle.js`

### Naming Conventions

- **Files**: `camelCase.js` for utilities/tools, `kebab-case.js` for transformers
- **Classes**: `PascalCase` (e.g., `DecodeTool`)
- **Functions**: `camelCase` (e.g., `runUniversalDecode`)
- **Constants**: `UPPER_SNAKE_CASE` (e.g., `MAX_HISTORY_ITEMS`)

## 🔧 Build Process

### Building Templates

```bash
npm run build:templates
```

This:
1. Reads the ordered list of tool templates from `templates/` (see `build/inject-tool-templates.js`)
2. Injects them into **`dist/index.html`** at the `#tool-content-container` marker (from `index.template.html`)
3. Produces the static HTML file served from `dist/`

**When to run:**
- After editing any template in `templates/`
- Before committing template changes

### Build Script Details

- **Directory creation**: Scripts create `dist/` (and subfolders) as needed
- **Full build**: `npm run build` runs tools injection, copy, transformer index, transform bundle, emoji data, template injection (see `package.json` and `build/README.md`)
- **Individual builds**: Each `npm run build:*` step can be run on its own

**Note:** The browser loads transforms from **`dist/js/bundles/transforms-bundle.js`** after a successful `npm run build:transforms` (and `npm run build:copy`).

## 🐛 Debugging

### Common Issues

1. **Template changes not showing**: Run `npm run build:templates` to rebuild **`dist/index.html`**, then refresh (or run `npm start` after a full `npm run build`)
2. **Tool not showing**: Check that:
   - `npm run build:tools` ran so `toolRegistry.js` and `index.template.html` include the new tool
   - Script tag order in **`index.template.html`** (loads before `app.js`)
   - Template file exists in `templates/` and is listed in `build/inject-tool-templates.js` when adding a new tab
3. **Tests failing**: Check file paths use `path.join(projectRoot, '...')`

### Browser Console

- Open browser DevTools (F12)
- Check console for errors
- Use `window.transforms` to see all transformers
- Use `window.steganography` for steganography helpers
- Use `window.emojiData` (after build) and `window.EmojiUtils` (`js/utils/emoji.js`) for emoji lists / splitting

## 📚 Documentation

- **Project README**: `README.md` — Overview and user guide
- **Templates**: `templates/README.md` — Editing tool templates
- **Build process**: `build/README.md` — Build scripts
- **Tool system**: `docs/TOOL-SYSTEM.md` — Templates, injection, UI vocabulary
- **Tool architecture**: `docs/TOOL_ARCHITECTURE.md`
- **UI components**: `docs/UI-COMPONENTS.md`
- **Themes**: `docs/THEMES.md` — Adding and editing themes

## ✅ Checklist Before Submitting

- [ ] Code follows existing style
- [ ] Tests pass (`npm test`)
- [ ] Templates built (`npm run build:templates`) if template files were edited
- [ ] Tested in browser (`npm run build`, then open `dist/index.html` or `npm start`)
- [ ] No console errors
- [ ] Documentation updated (if needed)
- [ ] JSDoc comments added (for new functions)

## 🤝 Questions?

- Check existing code for examples
- Review `docs/TOOL_ARCHITECTURE.md` and `docs/TOOL-SYSTEM.md` for architecture details
- Look at similar features to understand patterns

Thank you for contributing! 🎉