### Install gemoji-parser Gem

Source: https://github.com/pilotmoon/popclip-extensions/blob/master/contrib/Emoji.popclipext/gemoji-parser/README.md

Instructions for adding the gemoji-parser gem to a Ruby application's Gemfile and installing it using Bundler, or installing it directly via the gem command.

```ruby
gem 'gemoji-parser'
```

```bash
$ bundle install
    $ gem install gemoji-parser
```

--------------------------------

### C Code Block Example

Source: https://github.com/pilotmoon/popclip-extensions/blob/master/source/MarkdownToRTF.popclipext/test-input.md

A basic C code block demonstrating a simple 'Hello, World!' program structure. This serves as an example of how code is rendered within Markdown.

```c
#include <stdio.h>
int main() {
  return 0;
}
```

--------------------------------

### Action Handler with Input and Options (TypeScript)

Source: https://context7.com/pilotmoon/popclip-extensions/llms.txt

An example of an ActionFunction handler written in TypeScript. It demonstrates how to process input text, apply user-defined options, manipulate the pasteboard, and interact with the PopClip environment (e.g., opening URLs, pressing keys). Dependencies include PopClip API and utility functions.

```typescript
export const action: ActionFunction<Options> = async (input, options) => {
  let text = input.text.trim();
  if (options.prompt) {
    text = options.prompt.trim() + "\n\n" + text;
  }
  pasteboard.text = text;
  popclip.openUrl("chatgpt://");
  await util.sleep(50);
  if (options.mode === "new") {
    popclip.pressKey("command n");
    await util.sleep(800);
  }
  popclip.pressKey("command v");
  await util.sleep(100);
  popclip.pressKey("return");
};
```

--------------------------------

### Derive Emoji Image Paths (Ruby)

Source: https://github.com/pilotmoon/popclip-extensions/blob/master/contrib/Emoji.popclipext/gemoji-parser/README.md

Explains how to use EmojiParser.image_path to get the filepath for an emoji's image, based on its symbol format. It also shows how to specify a custom base path, useful for CDN references.

```ruby
EmojiParser.image_path('tropical_fish')
# "unicode/1f420.png"

EmojiParser.image_path('tropical_fish', '//cdn.fu/emoji/')
# "//cdn.fu/emoji/1f420.png"
```

--------------------------------

### JavaScript Extension Configuration for PopClip

Source: https://context7.com/pilotmoon/popclip-extensions/llms.txt

Configures PopClip extensions using JavaScript with CommonJS module exports. Includes inline metadata comments for extension properties and defines action functions. This example demonstrates text transformation with an optional randomness feature.

```javascript
// #popclip
// name: Alternating Case
// identifier: com.pilotmoon.popclip.extension.alternating-case
// description: Change the text to AlTeRnAtInG CaSe, with optional randomness.
// icon: noun_sponge_575115.svg
// popclipVersion: 4151

function alternatingCase(string, randomness) {
  function rnd() {
    return randomness ? Math.random() : 0;
  }
  function start() {
    return rnd() < 0.5 ? 0 : 1;
  }
  function step() {
    const x = rnd();
    if (x < 0.8) return 2;
    if (x < 0.9) return 3;
    return 1;
  }
  const characters = string.toLowerCase().split("");
  for (let item = start(); item < characters.length; item += step()) {
    characters[item] = characters[item].toUpperCase();
  }
  return characters.join("");
}

module.exports = {
  action: (selection, options) => {
    popclip.pasteText(
      alternatingCase(selection.text, options.randomness),
    );
  },
  options: [
    {
      identifier: "randomness",
      label: "Add Randomness",
      type: "boolean",
    },
  ],
};

```

--------------------------------

### Helper: Transform Lines (TypeScript)

Source: https://context7.com/pilotmoon/popclip-extensions/llms.txt

Demonstrates the use of the `transformLines` helper function from `@popclip/helpers` in TypeScript. This function applies a given transformation to each line of a multi-line string while preserving whitespace and indentation. Examples show converting lines to uppercase and reversing each line, including its usage within an action handler to paste the transformed text.

```typescript
import { transformLines } from "@popclip/helpers";

// Transform each line to uppercase while preserving whitespace
const result = transformLines("  hello\n  world", (s) => s.toUpperCase());
// Returns: "  HELLO\n  WORLD"

// Use in action handler
export const action: ActionFunction = (input) => {
  const transformed = transformLines(input.text, (line) => {
    return line.split("").reverse().join("");
  });
  popclip.pasteText(transformed);
};
```

--------------------------------

### Build and Quality Commands (Bash)

Source: https://context7.com/pilotmoon/popclip-extensions/llms.txt

Essential shell commands for managing the PopClip extension development workflow. Includes commands for type checking, linting code with Biome, auto-formatting, and converting legacy configuration files.

```bash
# Type-check all TypeScript files without emitting output
npm run check

# Lint codebase with Biome
npx biome check .

# Auto-format code with Biome
npx biome format . --write

# Convert legacy Config.plist to YAML format
# (run from within an extension directory)
misc/pcxconvert
```

--------------------------------

### Get TextWrangler Bundle Identifier with AppleScript

Source: https://github.com/pilotmoon/popclip-extensions/blob/master/contrib/TextWrangler.popclipext/README.md

This AppleScript command retrieves the bundle identifier for the TextWrangler application. It is useful for scripting interactions with TextWrangler.

```applescript
osascript -e 'id of app "TextWrangler"'
```

--------------------------------

### Multiple Actions with Regex Matching (TypeScript)

Source: https://context7.com/pilotmoon/popclip-extensions/llms.txt

Defines multiple actions (encode and decode) within a single extension using TypeScript. Each action has specific properties like an icon, title, and a `code` handler. The `decode` action includes a `regex` property, enabling it to appear conditionally based on the matched text pattern, showcasing conditional visibility.

```typescript
const encode: Action = {
  icon: 'square filled 64',
  title: 'Base64 Encode',
  code: (input, options) => {
    popclip.pasteText(util.base64Encode(input.text, {
      urlSafe: options.variant === 'url',
      trimmed: options.trim === true
    }))
  }
}

const decode: Action = {
  regex: /^[A-Za-z0-9+_\-/]+=?=?$/, 
  icon: 'square 64',
  title: 'Base64 Decode',
  code (input) {
    popclip.pasteText(util.base64Decode(input.text))
  }
}

export const actions = [encode, decode]
```

--------------------------------

### TypeScript Configuration for Extensions (JSON)

Source: https://context7.com/pilotmoon/popclip-extensions/llms.txt

A recommended TypeScript configuration file (`tsconfig.json`) for PopClip extension development. It enables strict type checking, specifies target ECMAScript version, includes necessary DOM and PopClip type definitions, and optimizes for modern module resolution.

```json
{
  "compilerOptions": {
    "target": "es2018",
    "lib": ["es2023", "dom", "dom.iterable"],
    "module": "preserve",
    "moduleResolution": "bundler",
    "baseUrl": "./lib",
    "skipLibCheck": true,
    "resolveJsonModule": true,
    "esModuleInterop": true,
    "strict": true,
    "noImplicitAny": false,
    "allowImportingTsExtensions": true,
    "types": ["node", "@popclip/types"],
    "isolatedModules": true,
    "noEmit": true
  },
  "include": ["./lib", "./source", "./contrib"]
}
```

--------------------------------

### Fetch and Render Emoji Data using XMLHttpRequest

Source: https://github.com/pilotmoon/popclip-extensions/blob/master/contrib/Emoji.popclipext/gemoji/db/index.html

This code snippet demonstrates how to fetch emoji data from a 'emoji.json' file using XMLHttpRequest and then render it using the `renderEmoji` function. It sets up an event listener for the request's completion and parses the JSON response.

```javascript
xhr = new XMLHttpRequest
xhr.onreadystatechange = function() {
  if (this.readyState == 4) {
    json = JSON.parse(this.responseText)
    renderEmoji(json)
  }
}
xhr.open('GET', 'emoji.json', false)
xhr.send(null)
```

--------------------------------

### YAML Extension Configuration for PopClip

Source: https://context7.com/pilotmoon/popclip-extensions/llms.txt

Provides declarative configuration for simple PopClip extensions using YAML. This format is suitable for extensions that trigger external applications via URL schemes or AppleScript, with metadata defined directly in the YAML file.

```yaml
name: Alfred
identifier: com.pilotmoon.popclip.extension.alfred
description: Activate Alfred with the selected text.
popclip version: 4151
icon: bowler.png
app:
  name: Alfred
  link: "https://www.alfredapp.com"
  bundleIdentifier: com.runningwithcrayons.Alfred
  checkInstalled: true
applescript: 'tell application id "com.runningwithcrayons.Alfred" to search "{popclip text}"'

```

--------------------------------

### Extension Options Configuration (TypeScript)

Source: https://context7.com/pilotmoon/popclip-extensions/llms.txt

Defines user-configurable options for a PopClip extension, supporting various types like strings, boolean toggles, and dropdown selections. This allows users to customize extension behavior directly from the PopClip settings.

```typescript
export const options = [
  {
    identifier: "prompt",
    label: "Prompt",
    type: "string",
    description: "Optional prompt to insert before the text. Leave blank for no prompt.",
  },
  {
    identifier: "mode",
    label: "Mode",
    type: "multiple",
    values: ["new", "current"],
    valueLabels: ["New Chat", "Current Chat"],
    description: "Whether to open a new chat or use the current chat.",
    inset: true,
  },
  {
    identifier: "randomness",
    label: "Add Randomness",
    type: "boolean",
  },
] as const;

type Options = InferOptions<typeof options>;
```

--------------------------------

### Extension Config File Structure (JSON)

Source: https://context7.com/pilotmoon/popclip-extensions/llms.txt

Defines the declarative configuration for a PopClip extension using JSON. It specifies metadata like identifier, name, icon, and URL, along with user-configurable options for customization. This structure allows for URL-based actions and custom option definitions.

```json
{
  "identifier": "com.pilotmoon.popclip.extension.amazon-search",
  "name": "Amazon",
  "icon": "amazon.svg",
  "url": "http://{popclip option site}/s?k={popclip text}",
  "popclipVersion": 3895,
  "description": "Search for products on Amazon.",
  "options": [
    {
      "label": "Amazon Site",
      "defaultValue": "www.amazon.com",
      "type": "multiple",
      "values": [
        "www.amazon.com",
        "www.amazon.co.uk",
        "www.amazon.de",
        "www.amazon.ca",
        "www.amazon.com.au"
      ],
      "identifier": "site"
    }
  ]
}
```

--------------------------------

### Kagi Translate Functionality

Source: https://github.com/pilotmoon/popclip-extensions/blob/master/source/KagiTranslate.popclipext/Readme.md

This section details how the Kagi Translate extension functions based on the input provided.

```APIDOC
## Kagi Translate URL Patterns

### Description
This section describes the URL patterns used by the Kagi Translate PopClip extension to handle different types of input (text vs. URL).

### Method
N/A (This describes URL patterns, not a specific HTTP request)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
N/A

## URL Patterns

- **Translate text:** `https://translate.kagi.com/?text=<text>` (when the selected text is not a URL)
- **Translate URL:** `https://translate.kagi.com/<url>` (when the selected text is a URL)
```

--------------------------------

### TypeScript Extension Configuration for PopClip

Source: https://context7.com/pilotmoon/popclip-extensions/llms.txt

Defines PopClip extension metadata, options, and action handlers using TypeScript. It supports inline metadata comments and exports action functions, allowing for complex text manipulations and service integrations. Dependencies include PopClip's runtime APIs.

```typescript
// #popclip
// name: Agenda
// identifier: com.pilotmoon.popclip.extension.agenda
// description: Capture text to an Agenda note.
// popclip version: 4688
// icon: agenda.svg
// app:
//   name: Agenda
//   link: https://agenda.com/
//   bundleIdentifier: com.momenta.agenda.macos
//   checkInstalled: true

type AgendaOptions = { title: string; noteTitle: string };

export const options: Option[] = [
  {
    identifier: "title",
    label: "Project Name",
    type: "string",
    description: "Name of project to capture to. Leave blank to capture to the active project.",
  },
  {
    identifier: "noteTitle",
    label: "Note Title",
    type: "string",
    defaultValue: "Clipping",
    description: "Title for clipped notes.",
  },
];

export const action: Action<AgendaOptions> = {
  captureHtml: true,
  code(input, options, context) {
    let text = input.markdown.trim();
    if (context.browserUrl) {
      text += `\n[${context.browserTitle || "Source"}](${context.browserUrl})`;
    }
    const url = new URL("agenda://x-callback-url/create-note");
    if (options.title) {
      url.searchParams.set("project-title", options.title);
    }
    url.searchParams.set("title", options.noteTitle);
    url.searchParams.set("text", text);
    popclip.openUrl(url);
  },
};

```

--------------------------------

### Tokenize and Detokenize Emoji Symbols (Ruby)

Source: https://github.com/pilotmoon/popclip-extensions/blob/master/contrib/Emoji.popclipext/gemoji-parser/README.md

Demonstrates how to convert Unicode emoji characters to their token string representations (e.g., 🙈 to :see_no_evil:) using EmojiParser.tokenize and vice versa using EmojiParser.detokenize.

```ruby
EmojiParser.tokenize("Test 🙈 🙊 🙉")
# "Test :see_no_evil: :speak_no_evil: :hear_no_evil:"

EmojiParser.detokenize("Test :see_no_evil: :speak_no_evil: :hear_no_evil:")
# "Test 🙈 🙊 🙉"
```

--------------------------------

### Render Emoji Data with JavaScript

Source: https://github.com/pilotmoon/popclip-extensions/blob/master/contrib/Emoji.popclipext/gemoji/db/index.html

This JavaScript function renders emoji data by cloning a template list item and populating it with emoji details. It handles both emoji characters and image sources, along with descriptions, aliases, and tags. The function also attaches the processed emoji text for searching.

```javascript
function renderEmoji(emojis) {
  var item, els, template = document.querySelector('li')
  for (var emoji, i=0; i < emojis.length; i++) {
    emoji = emojis[i]
    item = template.cloneNode(true)
    els = item.querySelectorAll('span')
    if (emoji.emoji) els[0].textContent = emoji.emoji
    else {
      var img = document.createElement('img')
      img.src = "../images/emoji/" + emoji.aliases[0] + ".png"
      els[0].appendChild(img)
    }
    els[1].textContent = emoji.description || ''
    els[2].innerHTML = emoji.aliases.map(function(n){ return '<span>'+n+'</span>' }).join(' ')
    els[3].innerHTML = emoji.tags.map(function(n){ return '<span>'+n+'</span>' }).join(' ')
    template.parentNode.appendChild(item)
    item._emojiText = (els[2].textContent + ' ' + els[3].textContent).replace(/_/g, '-')
  }
}
```

--------------------------------

### Quit PopClip Application with AppleScript

Source: https://github.com/pilotmoon/popclip-extensions/blob/master/contrib/TextWrangler.popclipext/README.md

This AppleScript command is used to quit the PopClip application. It can be helpful during development or when needing to restart the PopClip service.

```applescript
osascript -e 'tell app "PopClip" to quit'
```

--------------------------------

### Find Emoji Character Objects (Ruby)

Source: https://github.com/pilotmoon/popclip-extensions/blob/master/contrib/Emoji.popclipext/gemoji-parser/README.md

Demonstrates using EmojiParser.find to retrieve Emoji::Character instances from various emoji symbol formats, including Unicode, token strings, and emoticons.

```ruby
emoji = EmojiParser.find(🐠)
emoji = EmojiParser.find('see_no_evil')
emoji = EmojiParser.find(';-)')
```

--------------------------------

### Parse Token Symbols to HTML (Ruby)

Source: https://github.com/pilotmoon/popclip-extensions/blob/master/contrib/Emoji.popclipext/gemoji-parser/README.md

Demonstrates parsing tokenized emoji symbols (e.g., :tropical_fish:) into custom HTML formats using EmojiParser.parse_tokens. The provided block processes each matched emoji.

```ruby
EmojiParser.parse_tokens("Test :tropical_fish:") do |emoji|
  %Q(<img src="#{emoji.image_filename}" alt=":#{emoji.name}:">).html_safe
end

# 'Test <img src="unicode/1f420.png" alt=":tropical_fish:">'
```

--------------------------------

### Search Emoji Functionality with JavaScript

Source: https://github.com/pilotmoon/popclip-extensions/blob/master/contrib/Emoji.popclipext/gemoji/db/index.html

Implements a search function that filters emoji list items based on a given query. It uses a regular expression to test against the stored emoji text and shows or hides list items accordingly. This function is debounced using `setTimeout` to improve performance during user input.

```javascript
function searchEmoji(query) {
  var el, re = new RegExp('\b' + query), els = document.querySelectorAll('li')
  for (var i=1; i < els.length; i++) {
    el = els[i]
    if ( !query || re.test(el._emojiText) ) {
      el.style.display = 'list-item'
    } else {
      el.style.display = 'none'
    }
  }
}

var timeout, search = document.querySelector('input[type=search]')
search.addEventListener('input', function() {
  var $this = this
  if (timeout) clearTimeout(timeout)
  timeout = setTimeout(function(){
    searchEmoji($this.value)
  }, 200)
}, false)

search.focus()
```

--------------------------------

### Add Custom Emoji Symbols (Ruby)

Source: https://github.com/pilotmoon/popclip-extensions/blob/master/contrib/Emoji.popclipext/gemoji-parser/README.md

Shows how to add custom emoji symbols using Emoji.create and then regenerate the parser's regex cache by calling EmojiParser.rehash! to include the new symbols.

```ruby
Emoji.create('boxing_kangaroo')
EmojiParser.rehash!
```

--------------------------------

### Concurrent Transform Generator (TypeScript)

Source: https://context7.com/pilotmoon/popclip-extensions/llms.txt

An asynchronous generator that processes items in parallel, applying transformations concurrently while automatically deduplicating identical requests. This is efficient for batch operations like translating multiple words or fetching similar data.

```typescript
import { concurrentTransform } from "@popclip/helpers";

// Translate multiple words concurrently, deduplicating requests
async function translateWords(words) {
  const results = [];
  for await (const translated of concurrentTransform(
    words,
    async (word) => {
      const response = await fetch(`/api/translate?word=${word}`);
      return await response.text();
    }
  )) {
    results.push(translated);
  }
  return results;
}

// Usage in action
export const action: ActionFunction = async (input) => {
  const words = input.text.split(/\s+/);
  const translations = [];
  for await (const translation of concurrentTransform(words, translateWord)) {
    translations.push(translation);
  }
  popclip.pasteText(translations.join(" "));
};

async function translateWord(word) {
  // Simulated API call
  await new Promise(resolve => setTimeout(resolve, 100));
  return word.toUpperCase();
}
```

--------------------------------

### Dynamic Action Population Function (TypeScript)

Source: https://context7.com/pilotmoon/popclip-extensions/llms.txt

A TypeScript `PopulationFunction` that dynamically generates an action based on the input selection. It evaluates mathematical expressions using `mathjs`, formats the result, and creates an action with the result as its title. The function handles potential errors, long inputs, and custom locale settings for decimal separators. It includes a maximum length for the displayed title.

```typescript
import { evaluate, format, typeOf } from "mathjs";

export const actions: PopulationFunction = (selection) => {
  const separator = util.localeInfo.decimalSeparator;

  if (selection.text.length > 1000) {
    return;
  }

  let text = selection.text.trim();
  const endsWithEquals = text.endsWith("=");
  if (endsWithEquals) {
    text = text.substring(0, text.length - 1);
  }

  text = text.replace(separator, ".");

  let result = evaluate(text);
  if (
    result === undefined ||
    typeof result === "function" ||
    typeof result === "string"
  ) {
    return;
  }

  if (typeOf(result) === "ResultSet") {
    const resultArray = result.valueOf();
    result = resultArray[resultArray.length - 1];
  }

  let resultString = format(result, { precision: 14 });
  const maxLength = 40;
  if (resultString.length > maxLength) {
    resultString = `${resultString.substring(0, maxLength)}…`;
  }

  resultString = resultString.replace(".", separator);

  return {
    title: resultString,
    icon: null,
    code: () => (endsWithEquals ? selection.text + resultString : resultString),
  };
};
```

--------------------------------

### Parse All Emoji Symbol Types (Ruby)

Source: https://github.com/pilotmoon/popclip-extensions/blob/master/contrib/Emoji.popclipext/gemoji-parser/README.md

Shows how to parse all types of emoji symbols (Unicode, token, emoticon) in a single pass using EmojiParser.parse. Options like `emoticons: false` can exclude specific symbol types. The block allows for custom transformations.

```ruby
EmojiParser.parse("Test 🐠 :scream: ;-)") { |emoji| "[#{emoji.name}]" }
# 'Test [tropical_fish] [scream] [wink]'

EmojiParser.parse("Test 🐠 :scream: ;-)", emoticons: false) do |emoji|
  "[#{emoji.name}]"
end
# 'Test [tropical_fish] [scream] ;-)'
```