creating-bookmarklets

# Bookmarklet Creation

## Critical Requirements

### Comment Style - ABSOLUTE
**Use ONLY `/* */` comments. NEVER use `//` comments.**

Bookmark execution contexts fail with `//` style. Every comment must use block format.

```javascript
/* ✓ Correct */
const x = 5; /* inline */

/* ✗ Wrong - breaks bookmarklets */
// const x = 5;
const y = 10; // inline
```

### IIFE Wrapper
All bookmarklets must wrap in IIFE:

```javascript
(function() {
  /* bookmarklet code */
})();
```

### Protocol Prefix
All delivered bookmarklets must begin with `javascript:` protocol:

```javascript
javascript:(function() {
  /* bookmarklet code */
})();
```

This makes the code immediately usable without requiring manual modification during installation.

## Workflow

### 1. Generate Pretty-Printed Code

Create readable source with:
- 2-space indentation
- Descriptive variable names
- Block comments for key sections
- Logical organization
- **Prepend `javascript:` protocol to the code**

**This version with `javascript:` prefix gets stored in GitHub and shown to users, making it ready for installation without manual modification.**

### 2. Provide Installation

**Default approach - reference installer:**
```
Install: https://austegard.com/web-utilities/bookmarklet-installer.html
```

Installer handles:
- Minification with Terser
- URL encoding
- Draggable link generation
- GitHub repo integration

**Alternative - generate link programmatically:**
Use Terser.js to create installable link if requested:

```javascript
async function createBookmarkletLink(code, title) {
  const minified = await Terser.minify(code);
  const encoded = encodeURIComponent(minified.code).replace(/'/g, "%27");
  return `<a href="javascript:${encoded}">${title}</a>`;
}
```

Requires: `<script src="https://cdn.jsdelivr.net/npm/terser/dist/bundle.min.js"></script>`

### 3. Deliverables

Always provide:
1. Pretty-printed source code **with `javascript:` protocol prepended**
2. Installation method (installer link or generated link)
3. Brief description of functionality
4. Usage instructions

The code should be delivered in a format ready for direct use - users should be able to copy the entire code block (including `javascript:`) without modification.

## Code Standards

### Error Handling
```javascript
(function() {
  try {
    /* main logic */
  } catch (error) {
    console.error('Bookmarklet error:', error);
    alert('Operation failed: ' + error.message);
  }
})();
```

### Console Logging
Include debug traces by default:

```javascript
console.log('Bookmarklet: Starting');
/* operations */
console.log('Bookmarklet: Complete');
```

### User Feedback
```javascript
/* Success */
alert('✓ Content copied to clipboard');

/* Error */
alert('✗ Failed to access clipboard');
```

## Common Patterns

### DOM Manipulation
```javascript
(function() {
  const element = document.querySelector('.target');
  if (!element) {
    alert('Element not found');
    return;
  }
  /* manipulate element */
})();
```

### Data Extraction
```javascript
(function() {
  const data = Array.from(document.querySelectorAll('.item'))
    .map(item => ({
      title: item.querySelector('.title')?.textContent.trim(),
      value: item.querySelector('.value')?.textContent.trim()
    }));
  
  console.log('Extracted:', data);
})();
```

### Clipboard Operations
```javascript
(function() {
  const text = 'content to copy';
  navigator.clipboard.writeText(text)
    .then(() => alert('✓ Copied'))
    .catch(err => {
      console.error('Clipboard error:', err);
      alert('✗ Copy failed');
    });
})();
```

### Dynamic Library Loading
```javascript
(function() {
  if (typeof someLibrary === 'undefined') {
    const script = document.createElement('script');
    script.src = 'https://cdn.example.com/library.js';
    script.onload = function() {
      /* proceed with logic */
    };
    document.head.appendChild(script);
  }
})();
```

## Browser Compatibility

Provide fallbacks for unsupported features:

```javascript
if (!navigator.clipboard) {
  alert('Clipboard API not supported');
  return;
}
```

## Constraints

**Cannot use:**
- External files (CSS, images) without embedding
- Build tools or preprocessing
- `//` style comments

**Can use:**
- Fetch API
- localStorage/sessionStorage
- Modern browser APIs
- CDN libraries (loaded dynamically)

## Testing

Before delivering:
1. Verify no `//` comments exist
2. Test in browser console wrapped in IIFE
3. Check error handling with missing DOM elements
4. Verify user feedback for all paths

## Example Output

```
javascript:(function() {
  /* Pretty-printed bookmarklet code */
})();

Install: https://austegard.com/web-utilities/bookmarklet-installer.html

Extracts all links from current page and copies to clipboard as markdown list. Works on any webpage.
```

## GitHub Storage

User repository: https://github.com/oaustegard/bookmarklets

Pretty-printed format matches storage requirements. Installer loads directly from this repo.