Skill: Edit Extensions

---
name: lucid-extension-edit
description: Modify an existing Lucid editor extension or use the lucid-extension-sdk. Use when the user asks to add, edit, or debug functionality in a Lucid editor extension, add a menu item / modal / custom shape / data connector, call an SDK API, or answer questions about the lucid-extension-sdk. Not for scaffolding a new package — use the lucid-extension-create skill for that.
---

# Edit a Lucid Editor Extension

Use this skill when the user is working in an existing Lucid editor extension project and wants to add features, change behavior, or understand an SDK API.

## Core rule: use the docs index first

For **any** question about the SDK or editor extension API, begin by loading the Lucid developer docs index:

```
https://lucid.readme.io/llms.txt
```
This file lists every reference page. Workflow on every SDK question:

1. Fetch `https://lucid.readme.io/llms.txt`. **Use a focused prompt** — a generic "summarize this" returns a high-level summary instead of the URL list. Instead ask for the URLs verbatim and name the topics you care about. Example prompt:
   > "Return the full raw contents of this file — it is an index of documentation URLs. Do not summarize. List every section heading and every URL verbatim. I specifically need URLs related to: \<topics from the user's query, e.g. menus, BlockProxy, modals\>."
2. Scan the returned list for entries relevant to the user's query (e.g. `BlockProxy`, `CustomBlockDefinition`, `EditorClient`, `Modal`, `DataConnector`, `OAuth`, formula functions, etc.).
3. Fetch the specific pages you identified — do not guess API shapes from memory. **In the fetch prompt, demand verbatim code and type signatures**, because the fetcher otherwise paraphrases. Example prompt:
   > "Show the exact code example(s) for \<thing\>. Quote code verbatim. Do not paraphrase type signatures, method names, or argument shapes. Include the exact method name and the full argument object shape."
4. Use those pages to answer the user or write the code, and cite the URLs you used so the user can verify.

Do not try to answer SDK questions without consulting `llms.txt` and the linked pages. If a relevant page isn't in the index, tell the user you couldn't find it rather than inventing APIs.

## Ground rules

- Packages in use: **`lucid-package`** (CLI) and **`lucid-extension-sdk`** (runtime).
- Prefer pnpm if the user has it installed. Pass `--mode pnpm` to `lucid-package` **before** the subcommand:
  - Correct: `npx lucid-package@latest --mode pnpm test-editor-extension`
  - Wrong: `npx lucid-package@latest test-editor-extension --mode pnpm`
- Before suggesting SDK version bumps, check:
  ```
  pnpm view lucid-extension-sdk version
  pnpm view lucid-package version
  ```
- **Ignore the `[email protected]` line.** Versions `1.0.0`–`1.0.5` were published in December 2021 and abandoned — active development lives on the `0.0.x` track and the `latest` dist-tag points there. But `1.0.5` is the highest semver on npm, so a bare `pnpm add lucid-extension-sdk` (no `@latest`) or a `^1.x` range resolves to the ancient `1.x`. If the project's `package.json` has `lucid-extension-sdk` on a `1.x` version or caret range, treat it as a misconfiguration and fix it:
  ```
  pnpm add lucid-extension-sdk@latest
  ```
  then pin to the `0.0.x` value (e.g. `"lucid-extension-sdk": "0.0.456"`) rather than `^1.0.5`. Any code you write should target the `0.0.x` API surface documented on lucid.readme.io.

## Minimal reference: context-menu item that opens a modal

The most common small task is "register a right-click menu item that opens a modal." The `CustomMenuItem` shape requires **both** `menuType` and `location` — omitting `location` is a type error even though older example code in the wild leaves it off.

```ts
// editorextensions/<ext>/src/extension.ts
import {EditorClient, Menu, MenuLocation, MenuType} from 'lucid-extension-sdk';
import modalHtml from '../resources/modal.html'; // raw-loaded by webpack

const client = new EditorClient();
const menu = new Menu(client);

client.registerAction('open-my-modal', () => {
    client.showModal('My Modal', 320, 400, modalHtml);
});

menu.addMenuItem({
    label: 'My Modal',
    action: 'open-my-modal',
    menuType: MenuType.Context,     // right-click menu; use MenuType.Main for top bar
    location: MenuLocation.Extension,
});
```
`MenuLocation` options: `Extension`, `File`, `Edit`, `View`, `Share`, `Export`, `Import`. `showModal(title, width, height, content)` takes an HTML string — no dev server or React required. For anything more involved (data connectors, custom shapes, CustomUI panels), fall through to `llms.txt`.

## Where code lives

In a package scaffolded by `lucid-package create`:

- `manifest.json` — declares extensions, products (`chart`, `spark`), scopes (`READ`, `WRITE`, `SHOW_MODAL`, `CUSTOM_UI`, `DOWNLOAD`, `NETWORK`, `OAUTH_TOKEN`, `USER_INFO`), and `codePath`.
- `editorextensions/<ext-name>/src/extension.ts` — entry point; registers menu items, actions, modals, shape definitions.
- `editorextensions/<ext-name>/src/` — additional TypeScript sources (modals, shape libraries, data connectors).
- `editorextensions/<ext-name>/resources/` — HTML/CSS/assets for Custom UI and modals (e.g., `import.html`).
- `webpack.config.js`, `tsconfig.json` — build config; avoid editing unless necessary.

## Typical edit workflow

1. **Understand the request.** Identify the SDK surface(s) likely involved (e.g. "add a right-click menu item" → `EditorClient`, menu registration; "add a modal" → `Modal`, `CustomUI`; "read shape data" → `BlockProxy`, `DataProxy`).
2. **Consult `llms.txt`** (see core rule above) and fetch the relevant reference pages.
3. **Make the edits** in the right files. Only request new `scopes` in `manifest.json` if the new feature actually needs them.
4. **Type-check:**
   ```
   npx lucid-package@latest --mode pnpm build-editor-extension <extension-name>
   ```
5. **Run locally for manual verification:**
   ```
   npx lucid-package@latest --mode pnpm test-editor-extension <extension-name>
   ```
   Dev server: editor extensions at `localhost:9900`, shape libraries at `localhost:9901`. Watches files and recompiles.
6. Tell the user how to reload in the editor (Developer menu → re-enter developer mode) if they need it.

## Updating the SDK

If the user wants (or the code needs) a newer SDK:

```
npx lucid-package@latest --mode pnpm update-sdk
```
Re-run `build-editor-extension` after update and fix any type errors surfaced by the newer types — reference the updated pages from `llms.txt`.

## Bundling for upload

When the user wants to ship:

```
npx lucid-package@latest --mode pnpm bundle
```
Produces the artifact they upload to the developer dashboard.

## Command reference (edit-mode subset)

| Purpose | Command |
|---|---|
| Watch + serve locally | `npx lucid-package@latest --mode pnpm test-editor-extension` |
| Debug build (no serve) | `npx lucid-package@latest --mode pnpm watch-editor-extension` |
| Production build / type check | `npx lucid-package@latest --mode pnpm build-editor-extension` |
| Update SDK | `npx lucid-package@latest --mode pnpm update-sdk` |
| Bundle for upload | `npx lucid-package@latest --mode pnpm bundle` |
| Add another extension to this package | `npx lucid-package@latest --mode pnpm create-editor-extension <name>` |

## Loading / reloading in the editor (reminders)

- Enable developer mode in Lucid account settings (upper-right, lucid.app) or via admin role.
- In the editor: Developer menu → "Enter developer mode" connects to the local dev server.
- Chrome 142+: may need to set "Local network access" to Allow in the address-bar lock icon.
- Safari is not supported for local extension loading — use Chrome.

## Answering SDK questions without code changes

If the user only asks a conceptual or API question (no code change needed), still follow the core rule: fetch `llms.txt`, pick the relevant page(s), and ground the answer in them. Link the specific doc pages you used so the user can verify.

## Fetch prompt cheat sheet

When calling Fetch, the *prompt* you pass determines whether you get verbatim content or a summary. Defaults lean toward summary, which silently loses API signatures. Always include:

- For `llms.txt`: "Return URLs verbatim. Do not summarize. I need URLs related to \<topic\>."
- For reference pages: "Quote code verbatim. Do not paraphrase type signatures, method names, or argument shapes."
- For guide pages: "Quote any code examples verbatim. Include exact method and property names."