{"owner":"pierrecomputer","repo":"pierre","hasSkills":true,"totalSkillsCount":67,"totalTokensCount":59470,"categories":["anthropic-skill","root-instruction","claude-rule","plugin-manifest"],"hasMcp":false,"mcpConfig":null,"found":[".agents/skills/browser-automation/SKILL.md",".agents/skills/testing-and-verification/SKILL.md",".agents/skills/tooling-and-dependencies/SKILL.md",".agents/skills/typescript-monorepo/SKILL.md",".agents/skills/worktrees-and-dev-servers/SKILL.md","AGENTS.md","CLAUDE.md","packages/diffs/README.md","packages/diffs/test/README.md","packages/highlights/README.md","packages/highlights/benchmark/README.md","packages/highlights/themes/README.md","packages/path-store/README.md","packages/pipes/README.md","packages/theme/README.md","packages/theme/zed/README.md","packages/theming/README.md","packages/trees/README.md","skills/INDEX.md","skills/diffs/SKILL.md","skills/diffs/references/api-core.md","skills/diffs/references/api-editor.md","skills/diffs/references/api-highlighting.md","skills/diffs/references/api-react.md","skills/diffs/references/api-rendering.md","skills/diffs/references/api-ssr.md","skills/diffs/references/api-types.md","skills/diffs/references/api-worker.md","skills/diffs/references/recipe-annotations.md","skills/diffs/references/recipe-code-view.md","skills/diffs/references/recipe-custom-highlighting.md","skills/diffs/references/recipe-edit-react.md","skills/diffs/references/recipe-edit-vanilla.md","skills/diffs/references/recipe-react.md","skills/diffs/references/recipe-ssr.md","skills/diffs/references/recipe-vanilla.md","skills/diffs/references/recipe-workers.md","skills/highlights/SKILL.md","skills/highlights/references/live.md","skills/highlights/references/rendering.md","skills/highlights/references/streaming.md","skills/highlights/references/themes.md","skills/theme/SKILL.md","skills/theme/references/api.md","skills/theme/references/recipe-editor.md","skills/theme/references/recipe-shiki.md","skills/theme/references/variants.md","skills/theming/SKILL.md","skills/theming/references/collections.md","skills/theming/references/colors.md","skills/theming/references/controller.md","skills/theming/references/react.md","skills/theming/references/recipe-multiple-controllers.md","skills/theming/references/recipe-one-controller.md","skills/theming/references/recipe-react.md","skills/theming/references/recipe-vanilla.md","skills/theming/references/resolver.md","skills/trees/SKILL.md","skills/trees/references/api-core.md","skills/trees/references/api-react.md","skills/trees/references/api-ssr.md","skills/trees/references/api-web-components.md","skills/trees/references/recipe-interactions.md","skills/trees/references/recipe-react.md","skills/trees/references/recipe-ssr.md","skills/trees/references/recipe-theme.md","skills/trees/references/recipe-vanilla.md"],"skills":{".agents/skills/browser-automation/SKILL.md":"---\nname: browser-automation\ndescription:\n Use when opening, inspecting, clicking, filling, snapshotting, or otherwise\n automating web pages for this repo, including local dev servers and\n browser-based verification.\n---\n\n# Browser Automation\n\nUse `agent-browser` for web automation in this repo. Run:\n\n```bash\nagent-browser --help\n```\n\nCore workflow:\n\n```bash\nagent-browser open \nagent-browser snapshot -i\nagent-browser click @e1\nagent-browser fill @e2 \"text\"\n```\n\nRe-run `agent-browser snapshot -i` after page changes so element refs stay\ncurrent.\n\nUse browser automation for behavior that needs a rendered page, real DOM state,\nor interactive verification. Prefer focused Bun tests for pure logic and\nnon-browser integration behavior.\n",".agents/skills/testing-and-verification/SKILL.md":"---\nname: testing-and-verification\ndescription:\n Use when adding or running tests, checking snapshots, choosing between Bun\n tests and Playwright, running lint/format/typecheck, or deciding the\n verification scope for a change.\n---\n\n# Testing and Verification\n\n## Baseline Commands\n\nAfter code changes, run the required baseline (moon tasks run from anywhere in\nthe repo, including CI-marked agent shells):\n\n```bash\nmoon run root:format root:lint\n```\n\nUseful check/fix pairs on the root project:\n\n```bash\nmoon run root:format-check\nmoon run root:format\nmoon run root:lint\nmoon run root:lint-fix\nmoon run root:lint-css\nmoon run root:lint-css-fix\n```\n\nFor code changes, also run the relevant typecheck (moon builds workspace\ndependencies first automatically):\n\n```bash\nmoonx :typecheck\n# or, scoped to what actually changed:\nmoonx :typecheck --affected\n```\n\nThe React Compiler lint rules (`react/*` in `.oxlintrc.json`) assume React.\n`packages/trees/src/render/**/*.tsx` and\n`packages/trees/src/components/**/*.tsx` are Preact, so an `overrides` entry\nthere turns `react/refs` off for those globs. Put new Preact components under\nthose directories instead of adding per-file `oxlint-disable` headers.\n\n## Unit and Integration Tests\n\nUse Bun's built-in test runner. Tests usually live in a `test/` folder inside\neach package and use `describe`, `test`, and `expect` from `bun:test`.\n\nPrefer unit or integration tests by default:\n\n```bash\nmoonx diffs:test\nmoonx trees:test\n```\n\n`moon run :test` runs every project's suite. Tests import workspace dependencies\nthrough their built dist, so moon builds those first; running `bun test`\ndirectly inside a package also works when dist is fresh.\n\n## Snapshots\n\nBun supports `toMatchSnapshot()`. Avoid new snapshot coverage unless it is\nshallow and narrowly scoped to the exact behavior under test.\n\nUpdate snapshots from the package directory:\n\n```bash\nbun test -u\n```\n\n## Browser and E2E Tests\n\nAdd Playwright/browser E2E tests only when behavior cannot be validated without\na real browser engine. Good candidates include computed style checks, shadow DOM\nboundaries, and browser-only rendering behavior.\n\nKeep E2E coverage small and high-value:\n\n```bash\nmoonx trees:coverage\nmoonx trees:test-e2e\nmoonx path-store:test-demo\nmoonx docs:test-e2e\n```\n\nIf E2E fixtures or dev servers are started in a worktree, follow the cleanup\ncontract from the `worktrees-and-dev-servers` skill.\n",".agents/skills/tooling-and-dependencies/SKILL.md":"---\nname: tooling-and-dependencies\ndescription:\n Use when running repo scripts, adding or changing dependencies, editing\n package.json files, installing packages, publishing packages, or deciding when\n pnpm package operations versus Bun runtime commands should be invoked.\n---\n\n# Tooling and Dependencies\n\n## Toolchain (proto)\n\n- Tool versions (bun, pnpm, node, moon, gh) are pinned in `.prototools` and\n managed by [proto](https://moonrepo.dev/docs/proto); its shims put the pinned\n versions on PATH inside the repo. `proto use` installs everything after a pin\n changes.\n- Bump a tool by editing `.prototools` only — never install tools globally or\n pin versions elsewhere. moon's version is additionally enforced by\n `versionConstraint` in `.moon/workspace.yml` and mirrored as the\n `@moonrepo/cli` catalog entry (for Vercel builders without proto); keep all\n three in sync.\n- CI and local shells resolve the same toolchain: CI installs it with\n `moonrepo/setup-toolchain`, which runs `proto install` against the same\n `.prototools`.\n\n## Package Manager and Runtime\n\n- Use `pnpm` for package operations: install, add, remove, dedupe, lockfile,\n package-runner, and publish work.\n- Do not use `bun`, `npm`, `yarn`, `npx`, or other package runners for package\n operations unless there is a specific documented reason.\n- Bun remains the direct TypeScript runtime and Bun test runner where current\n moon tasks use it. Local scripts may still be `.ts` files without a separate\n compile step.\n\n## Dependency Catalog\n\nThis monorepo uses the `catalog` in `pnpm-workspace.yaml`.\n\n- Never add a version directly to an individual package's `package.json` by\n default.\n- To add a dependency:\n 1. Add the exact version to `pnpm-workspace.yaml` under `catalog`, for example\n `\"new-package\": \"1.2.3\"`.\n 2. Reference it from the package with `\"new-package\": \"catalog:\"`.\n- Do not run `pnpm add ` inside a package directory; it writes direct\n versions and breaks the catalog pattern unless you manually normalize them.\n- Published packages may intentionally use ranges for end-user compatibility.\n `apps/docs` should use catalog versions; published packages such as\n `packages/diffs` may use ranges only when that is intentional.\n\n## Tasks\n\n- All build/dev/test/lint entrypoints are moon tasks; package.json scripts exist\n only for npm lifecycle hooks (`prepublishOnly`). Never add task scripts back\n to a package.json.\n- Tasks are defined in `.moon/tasks/*.yml` (inherited) and each project's\n `moon.yml`. Repo-wide tooling (format, lint, icons, clean) lives on the `root`\n project.\n- Run tasks from anywhere in the repo:\n\n```bash\nmoon run :\nmoonx : # same engine; shorthand for moon exec\nmoonx : -- --flags # forward arguments after --\nmoon run :test # a task across every project that has it\nmoon tasks # discover a project's tasks\n```\n\n`moon run` and `moonx` (an alias binary for `moon exec`) execute the same action\npipeline: identical dependency resolution, caching, and affected support. Use\nthem interchangeably; docs write `moon run` for canonical commands and `moonx`\nin interactive examples. The one practical difference: `moonx`/`moon exec`\nexposes CI-behavior overrides (`--ignore-ci-checks`, `--ci `) that\n`moon run` lacks. `moon ci` is a third thing — the affected-aware orchestrator\nused only by `.github/workflows/ci.yml`; never reach for it locally.\n\nmoon builds dependency projects first (`deps: ['^:build']`), caches outputs, and\nskips tasks whose inputs have not changed. Local-only tasks set explicit options\ninstead of moon presets (presets force `runInCI: skip`, which moon refuses to\nrun in CI-detected shells; agent harnesses export `CI=1`):\n\n- No graph edges at all (formatters, benchmarks, wt, servers spawned by\n playwright): use `runInCI: 'always'` — runnable everywhere, and never in the\n CI pipeline because a task with no deps or dependents is never affected\n through the graph.\n- Connected to the build graph (dev/prod, e2e variants, publish guards): keep\n `runInCI: 'skip'` — `moon ci --include-relations` runs affected\n runInCI-enabled tasks even when unrequested, which would pull them into CI.\n Run them in CI-marked shells with `moonx --ignore-ci-checks` (works\n regardless of the shell's CI env). For non-moon commands that CI-gate\n themselves, unset the var instead: `CI= pnpm publish --dry-run`.\n",".agents/skills/typescript-monorepo/SKILL.md":"---\nname: typescript-monorepo\ndescription:\n Use when adding or changing packages/apps, TypeScript configs, workspace\n dependencies, package references, exports, or monorepo project-reference\n relationships.\n---\n\n# TypeScript Monorepo\n\n## TypeScript\n\nUse TypeScript everywhere practical. Compiler settings are intentionally fairly\nstrict.\n\n- Shared compiler options live in `tsconfig.options.json`.\n- Root `tsconfig.json` manages project references across the monorepo.\n- Typechecking uses TypeScript 7's native `tsc` (the successor to the `tsgo`\n preview) and runs through moon: `moonx :typecheck` (moon builds\n workspace dependencies first, since types resolve through each dependency's\n built dist). Next runs the same `tsc` for its build-time check through\n `experimental.useTypeScriptCli`, which is on by default since Next 16.3.\n\n## Project References\n\nWhen adding a new package or app:\n\n- Add it to the root `tsconfig.json` references.\n- Ensure its local `tsconfig.json` follows existing package/app patterns.\n- Give it a `moon.yml` (language, layer, tags, and any project-specific tasks);\n shared tasks come from `.moon/tasks/*.yml` via tags or project language.\n\nWhen one workspace package depends on another:\n\n- Add the dependency as `workspace:*` in the consuming package.\n- Add the dependency to the consuming package's TypeScript `references` block\n when needed for accurate and fast typechecking.\n\n## Workspace Dependencies\n\nUse the `pnpm-workspace.yaml` catalog rules from `tooling-and-dependencies` for\nexternal packages. Use `workspace:*` for internal package dependencies.\n\nIf a package is published, review its `exports`, `typesVersions`, `files`, peer\ndependencies, and its moon `prepublish` task chain before changing public\nentrypoints or dependency ranges.\n",".agents/skills/worktrees-and-dev-servers/SKILL.md":"---\nname: worktrees-and-dev-servers\ndescription:\n Use when working with the repo's moonx root:wt worktree helper, Pierre-managed\n worktrees, dev-server port offsets, stale server cleanup, Playwright fixtures,\n or Chrome debug instances. Do not use this as a substitute for host-provided\n workspace isolation.\n---\n\n# Worktrees and Dev Servers\n\nPierre includes a repo-specific `git worktree` helper for local/manual\nparallelization outside host-managed agent workspaces. Managed Pierre worktrees\nlive at:\n\n```text\n~/pierre/pierre-worktrees//\n```\n\nEach managed Pierre worktree owns a port offset so dev servers, E2E fixtures,\nand the Chrome remote-debug instance do not collide. The main clone keeps\nhistorical default ports; linked Pierre worktrees shift ports.\n\nIf you are already inside a Conductor, Codex, Claude, or other host-provided\nworkspace, do not create another worktree unless the user explicitly asks for a\nPierre-managed worktree. Still use this skill when you start repo dev servers or\nE2E fixtures, because the cleanup and port-offset rules apply to those scripts.\n\n## Worktree Commands\n\nThe `wt` suite is defined in `scripts/wt.ts`, exposed as the `root:wt` moon\ntask, and manages only Pierre-managed worktrees:\n\n```bash\nmoonx root:wt -- new # create a worktree, allocate offset, pnpm install\nmoonx root:wt -- rm # kill its processes, remove the worktree\nmoonx root:wt -- clean # kill zombie servers on all managed worktree ports\nmoonx root:wt -- clean # clean one managed worktree\nmoonx root:wt -- ps # show per-worktree port status (LISTEN / -)\nmoonx root:wt -- list # summary of managed + external worktrees\n```\n\nPort-binding moon tasks read the offset from `/.env.worktree` via\ntheir `envFile` option. Before starting, dev tasks run `scripts/run-dev.sh` to\nkill any stale process bound to the target port.\n\n## Cleanup Contract\n\nIf you start dev servers, Playwright fixtures, or Chrome debug instances inside\na worktree, run cleanup before completing your turn:\n\n```bash\nmoonx root:wt -- clean \n```\n\nUse `moonx root:wt -- clean` when you do not know the slug or need to clean\nevery managed worktree. Use `moonx root:wt -- rm ` only when intentionally\ntearing down the worktree itself.\n","AGENTS.md":"# PierreJS Monorepo\n\n## Agent Environment\n\nSet `AGENT=1` at the start of every terminal session so Bun's test runner emits\nAI-friendly output:\n\n```bash\nexport AGENT=1\n```\n\nMost local moon tasks (formatters, benchmarks, worktree management) are\nconfigured with `runInCI: 'always'` so they keep working in CI-marked shells\nlike agent harnesses. Tasks connected to the build graph (dev servers, prod\nserves, e2e variants, publish guards) stay CI-skipped — run those with\n`moonx --ignore-ci-checks`, e.g.\n`moonx docs:dev-diffs --ignore-ci-checks`. For non-moon commands that CI-gate\nthemselves, unset the var: `CI= pnpm publish --dry-run`.\n\n## Toolchain\n\n- Tool versions (bun, pnpm, node, moon, gh) are pinned in `.prototools` and\n managed by [proto](https://moonrepo.dev/docs/proto); run `proto use` if a tool\n is missing or a pin changed. Never install toolchain versions globally; bump\n pins only in `.prototools`.\n- [moon](https://moonrepo.dev/docs) is the task runner; `package.json` scripts\n are npm lifecycle hooks only.\n\n## Core Rules\n\n- Use `pnpm` for install/add/remove/dedupe/package-manager and publishing work.\n Do not use `bun`, `npm`, `yarn`, `npx`, or similar tools for package\n operations unless there is a specific reason.\n- Dependencies use the `catalog` in `pnpm-workspace.yaml`. Never add dependency\n versions directly to package-level `package.json` files unless a published\n package intentionally needs its own range.\n- Run tasks through moon: `moon run :` (or the `moonx` shorthand)\n works from anywhere in the repo. `moonx : -- args` forwards\n arguments. Discover tasks with `moon tasks `.\n- Preserve trailing newlines at the end of files.\n- Setup steps for a fresh clone live in `CONTRIBUTING.md`.\n\n## Licensing\n\nEvery package in this repo is licensed under Apache 2.0. When adding a new\npackage under `packages/*` or `apps/*`:\n\n- Set `\"license\": \"apache-2.0\"` in its `package.json`.\n- Add an Apache 2.0 `LICENSE.md` at the package root — copy one from an existing\n package (e.g. `packages/trees/LICENSE.md`).\n\nVendored third-party code keeps its original license; record that attribution in\na `NOTICE.md` next to the package rather than changing its LICENSE.\n\n`moon run root:check-licenses` enforces both requirements and runs in CI on\nevery PR.\n\n## Skills\n\nDomain-specific context and conventions live in `.agents/skills/`. Before\nstarting any task:\n\n1. List `.agents/skills/*/SKILL.md`\n2. Read only each skill's frontmatter description to identify relevant skills\n3. Read only the full `SKILL.md` files relevant to your task\n\nDo not load skills that are not relevant to the task.\n\n## Agent Artifacts\n\nWrite agent-only planning and scratch artifacts under `.agents/ignore/` by\ndefault:\n\n- Plans: `.agents/ignore/plans/YYYY-MM-DD-.md`\n- Specs: `.agents/ignore/specs/YYYY-MM-DD-.md`\n\n`.agents/ignore/` is gitignored. Do not put source files, tests, or committed\ndocumentation there.\n\n## Verification Baseline\n\nAfter code changes, verification is not complete until you have run these from\nanywhere in the repo:\n\n```bash\nmoon run root:format root:lint\n```\n\nAlso run the affected typecheck and focused tests for the changed area, e.g.\n`moonx :typecheck` and `moonx :test` (or\n`moonx :typecheck --affected`). For docs-only or AGENTS/skill-only changes,\nformatting and linting are sufficient unless the edit touches executable code or\npackage config.\n\n## Code Readability\n\n- When adding non-trivial helpers, prefer a short comment directly above the\n function explaining what the helper does and why it exists.\n- Write comments for readers new to the codepath. Avoid vague shorthand like\n \"snapshot\" unless you immediately explain what data is captured or derived.\n- Prefer function-level comments over many inline comments. Use inline comments\n only when a specific step is still non-obvious.\n- Keep comments concrete and behavior-focused.\n","CLAUDE.md":"@AGENTS.md\n","packages/diffs/README.md":"","packages/diffs/test/README.md":"","packages/highlights/README.md":"","packages/highlights/benchmark/README.md":"","packages/highlights/themes/README.md":"","packages/path-store/README.md":"","packages/pipes/README.md":"","packages/theme/README.md":"","packages/theme/zed/README.md":"","packages/theming/README.md":"","packages/trees/README.md":"","skills/INDEX.md":"# Pierre package skills\n\nUse these skills when an app or site consumes a Pierre package. Read the\nselected `SKILL.md` first. Load only the API or recipe reference that matches\nthe task.\n\n| Skill | Use it for |\n| --------------------------------- | --------------------------------------------------------------------------------------------------- |\n| [diffs](diffs/SKILL.md) | Render or edit code files, diffs, patches, and merge conflicts with `@pierre/diffs`. |\n| [highlights](highlights/SKILL.md) | Generate HTML or themed tokens, stream code, and apply incremental edits with `@pierre/highlights`. |\n| [theme](theme/SKILL.md) | Select and load a Pierre syntax or editor theme from `@pierre/theme`. |\n| [theming](theming/SKILL.md) | Build runtime theme collections, resolvers, controllers, and color mappings with `@pierre/theming`. |\n| [trees](trees/SKILL.md) | Render and control an interactive file tree with `@pierre/trees`. |\n\n## Package relationship\n\n`@pierre/theme` supplies theme objects. `@pierre/theming` selects, resolves, and\nmaps those objects. `@pierre/diffs` and `@pierre/trees` render code and file\ntrees with the selected theme.\n\n`@pierre/highlights` generates standalone HTML or tokens using Zed-compatible\nthemes from `@pierre/highlights/themes`. Its theme objects use a different\nformat from the Shiki and VS Code themes in `@pierre/theme`.\n","skills/diffs/SKILL.md":"---\nname: diffs\ndescription:\n Use when an app uses @pierre/diffs to render or edit code files, diffs,\n patches, merge conflicts, or CodeView review surfaces, including React,\n vanilla JavaScript, SSR, workers, annotations, selection, and custom syntax\n languages or themes.\n---\n\n# `@pierre/diffs`\n\nUse `@pierre/diffs` to render syntax-highlighted files and diffs. Use its\noptional editor, SSR, and worker entries for those capabilities.\n\nFor standalone HTML or token generation with `@pierre/highlights`, read the\n[highlights skill](../highlights/SKILL.md).\n\n## Install\n\n```bash\npnpm add @pierre/diffs\n```\n\nInstall `react` and `react-dom` when the app uses the React entry.\n\n## Select an API reference\n\n| Surface | Reference |\n| ------------------------------------------------------------ | ------------------------------------------------------ |\n| Root components, parsing, and file extension APIs | [Core API](references/api-core.md) |\n| Languages, themes, highlighter state, and streams | [Highlighting API](references/api-highlighting.md) |\n| Renderers, managers, DOM helpers, comparisons, and constants | [Low-level rendering API](references/api-rendering.md) |\n| Shared data, option, render, selection, and editor types | [Shared types](references/api-types.md) |\n| `@pierre/diffs/react` | [React API](references/api-react.md) |\n| `@pierre/diffs/edit` | [Editor API](references/api-editor.md) |\n| `@pierre/diffs/ssr` | [SSR API](references/api-ssr.md) |\n| `@pierre/diffs/worker` and worker scripts | [Worker API](references/api-worker.md) |\n\n## Select a recipe\n\n| Task | Recipe |\n| ----------------------------------- | ------------------------------------------------------------------------ |\n| Render a file or diff in React | [Render with React](references/recipe-react.md) |\n| Render a file or diff without React | [Render with vanilla JavaScript](references/recipe-vanilla.md) |\n| Build a virtualized review surface | [Use CodeView](references/recipe-code-view.md) |\n| Edit a React surface or CodeView | [Edit with React](references/recipe-edit-react.md) |\n| Edit a vanilla surface or CodeView | [Edit with vanilla JavaScript](references/recipe-edit-vanilla.md) |\n| Preload markup on the server | [Use SSR](references/recipe-ssr.md) |\n| Highlight through a worker pool | [Use workers](references/recipe-workers.md) |\n| Add line annotations and selection | [Add annotations and selection](references/recipe-annotations.md) |\n| Register a custom language or theme | [Register custom highlighting](references/recipe-custom-highlighting.md) |\n","skills/diffs/references/api-core.md":"# Core API\n\nThis reference covers components, parsing, merge conflicts, and file extension\nAPIs from `@pierre/diffs`.\n\n## Contents\n\n- [File components](#file-components)\n- [Virtualized components](#virtualized-components)\n- [`File` members](#file-members)\n- [`FileDiff` members](#filediff-members)\n- [`CodeView` members](#codeview-members)\n- [Parsing and patch APIs](#parsing-and-patch-apis)\n- [Merge conflict APIs](#merge-conflict-apis)\n- [Annotation APIs](#annotation-apis)\n- [File extension APIs](#file-extension-apis)\n\n## File components\n\n| Export | Kind | Purpose |\n| --------------------------------------- | -------- | ------------------------------------------------------------- |\n| `File` | Class | Renders one syntax-highlighted file. |\n| `FileOptions` | Type | Configures file display, interaction, slots, and callbacks. |\n| `FileRenderProps` | Type | Defines file input and a render target. |\n| `FileHydrateProps` | Type | Defines file input and preloaded markup for hydration. |\n| `FileDiff` | Class | Renders a file diff from files or parsed metadata. |\n| `FileDiffOptions` | Type | Configures diff display, interaction, slots, and callbacks. |\n| `FileDiffRenderBaseProps` | Type | Defines shared diff render input. |\n| `FileDiffRenderProps` | Type | Adds files or parsed metadata to diff render input. |\n| `FileDiffHydrationProps` | Type | Defines diff input and preloaded markup for hydration. |\n| `FileDiffType` | Type | Identifies a standard or unresolved diff instance. |\n| `UnresolvedFile` | Class | Renders one file with merge conflict controls. |\n| `UnresolvedFileOptions` | Type | Configures merge conflict display and callbacks. |\n| `UnresolvedFileRenderProps` | Type | Defines merge conflict render input. |\n| `UnresolvedFileHydrationProps` | Type | Defines merge conflict input for hydration. |\n| `MergeConflictActionsTypeOption` | Type | Selects no actions, default actions, or a custom renderer. |\n| `RenderMergeConflictActions` | Type | Defines a vanilla conflict action renderer. |\n| `getUnresolvedDiffHunksRendererOptions` | Function | Converts unresolved-file options to hunk renderer options. |\n| `CodeView` | Class | Renders a virtualized list of files and diffs. |\n| `CodeViewOptions` | Type | Configures list layout, items, slots, selection, and editing. |\n| `CodeViewLineSelection` | Type | Associates a selected range with one item ID. |\n| `CodeViewRenderedFileItem` | Type | Describes one mounted file item. |\n| `CodeViewRenderedDiffItem` | Type | Describes one mounted diff item. |\n| `CodeViewRenderedItem` | Type | Represents a mounted file or diff item. |\n| `CodeViewCoordinator` | Type | Coordinates React slots with the vanilla list. |\n| `CodeViewSlotSnapshot` | Type | Describes mounted items and list header or footer hosts. |\n| `CodeViewScrollListener` | Type | Receives list scroll changes. |\n| `CODE_VIEW_FILE_OPTION_KEYS` | Value | Lists file options that `CodeView` passes to an item. |\n| `CODE_VIEW_DIFF_OPTION_KEYS` | Value | Lists diff options that `CodeView` passes to an item. |\n\n## Virtualized components\n\n| Export | Kind | Purpose |\n| -------------------------------------------------- | ----- | ----------------------------------------------------------- |\n| `Virtualizer` | Class | Tracks a simple viewport and connected render instances. |\n| `VirtualizerConfig` | Type | Configures overscroll, observation margin, and resize logs. |\n| `VirtualizedFile` | Class | Adds simple viewport behavior to `File`. |\n| `VirtualizedFileDiff` | Class | Adds simple viewport behavior to `FileDiff`. |\n| `VIRTUALIZED_FILE_DIFF_LAYOUT_CHECKPOINT_INTERVAL` | Value | Sets the line interval for virtual diff layout checkpoints. |\n\n## `File` members\n\n| Member | Purpose |\n| --------------------------------------------- | ---------------------------------------------------- |\n| `new File(options?, workerManager?)` | Creates one file renderer. |\n| `render(props)` | Renders file contents. |\n| `hydrate(props)` | Attaches to preloaded file markup. |\n| `rerender()` | Renders the current file again. |\n| `setOptions(options)` | Replaces file options. |\n| `setThemeType(themeType)` | Selects system, light, or dark theme mode. |\n| `onThemeChange()` | Applies a changed theme. |\n| `setLineAnnotations(annotations)` | Replaces file annotations. |\n| `setSelectedLines(range, options?)` | Replaces the selected line range. |\n| `setEditorActiveLine(line, options?)` | Marks the editor's active line. |\n| `getHoveredLine()` | Gets the current hovered line. |\n| `getOrCreateLineCache(file?)` | Gets cached source lines. |\n| `attachEditor(editor)` | Attaches an editor and returns a detach function. |\n| `applyDocumentChange(document, annotations?)` | Applies an editor document update. |\n| `updateRenderCache(tokens, themeType)` | Updates highlighted token cache entries. |\n| `primeHighlightCache()` | Preloads the highlighted file result. |\n| `renderPlaceholder(height)` | Renders a fixed-height placeholder. |\n| `virtualizedSetup()` | Prepares the instance for a virtualizer. |\n| `flushManagers()` | Applies deferred interaction and size manager state. |\n| `cleanUp(recycle?)` | Releases rendered resources. |\n\n## `FileDiff` members\n\n`FileDiff` supports the shared `File` update, selection, annotation, editor,\nhydration, placeholder, and cleanup members with diff data.\n\n| Member | Purpose |\n| -------------------------------------------- | ------------------------------------------------ |\n| `new FileDiff(options?, workerManager?)` | Creates one diff renderer. |\n| `render(props)` | Parses or renders diff input. |\n| `hydrate(props)` | Attaches to preloaded diff markup. |\n| `rerender()` | Renders the current diff again. |\n| `setOptions(options)` | Replaces diff options. |\n| `getLineIndex(line, side?)` | Maps a displayed line to row and column indexes. |\n| `handleExpandHunk(index, direction, count?)` | Handles a hunk expansion request. |\n| `expandHunk(index, direction, count?)` | Expands hidden context around one hunk. |\n| `completeEditSession()` | Recomputes diff metadata after an edit session. |\n| `isLineRenderable(line)` | Tests whether an additions line is visible. |\n| `getNearestRenderableLine(line, direction)` | Finds a visible additions line. |\n| `revealLine(line)` | Expands context to show an additions line. |\n| `primeHighlightCache(diff?)` | Preloads the highlighted diff result. |\n\n## `CodeView` members\n\n| Member | Purpose |\n| ---------------------------------------- | -------------------------------------------- |\n| `new CodeView(options?, workerManager?)` | Creates one virtualized list. |\n| `setup(root)` | Attaches the list to its scroll root. |\n| `setItems(items)` | Replaces all items. |\n| `addItem(item)` | Appends one item. |\n| `addItems(items)` | Appends several items. |\n| `getItem(id)` | Gets one item by ID. |\n| `updateItem(item)` | Replaces one item by ID. |\n| `updateItemId(oldId, newId)` | Changes one item ID. |\n| `getEditor(id)` | Gets the active editor for an item. |\n| `scrollTo(target)` | Scrolls to a position, item, line, or range. |\n| `setSelectedLines(selection, options?)` | Sets the selected item and range. |\n| `getSelectedLines()` | Gets the selected item and range. |\n| `clearSelectedLines(options?)` | Clears the selected lines. |\n| `setOptions(options)` | Replaces list options. |\n| `onThemeChange()` | Applies a changed theme to list items. |\n| `render(immediate?)` | Schedules or performs a render. |\n| `getWindowSpecs()` | Gets the current virtual window. |\n| `getContainerElement()` | Gets the scroll content element. |\n| `getHeaderElement()` | Gets the list header host. |\n| `getFooterElement()` | Gets the list footer host. |\n| `getRenderedItems()` | Gets mounted items. |\n| `setSlotCoordinator(coordinator?)` | Sets the external slot coordinator. |\n| `getSlotSnapshot(coordinator)` | Gets the coordinator's mounted slot state. |\n| `subscribeToScroll(listener)` | Subscribes to scroll changes. |\n| `getLocalTopForInstance(instance)` | Gets an instance offset inside the list. |\n| `getTopForItem(id)` | Gets an item offset inside the list. |\n| `instanceChanged(instance, layoutDirty)` | Reports a render instance change. |\n| `reset()` | Clears items and render state. |\n| `cleanUp()` | Releases list resources. |\n\n## Parsing and patch APIs\n\n| Export | Purpose |\n| ---------------------------- | ----------------------------------------------------- |\n| `parseDiffFromFile` | Creates `FileDiffMetadata` from old and new files. |\n| `parsePatchFiles` | Parses a patch string into file diff metadata. |\n| `processPatch` | Parses one patch section. |\n| `processFile` | Converts one parsed patch file to `FileDiffMetadata`. |\n| `getSingularPatch` | Selects one file patch from a patch string. |\n| `trimPatchContext` | Limits unchanged context in patch text. |\n| `hydratePartialDiff` | Adds loaded file contents to partial diff metadata. |\n| `cloneFileDiffMetadata` | Creates a structural copy of diff metadata. |\n| `cleanLastNewline` | Normalizes the final newline for diff input. |\n| `getLineEndingType` | Detects a file's line-ending sequence. |\n| `getTotalLineCountFromHunks` | Counts rendered rows across hunks. |\n| `parseLineType` | Parses one patch line marker and content. |\n| `ParsedLine` | Describes the result from `parseLineType`. |\n\n## Merge conflict APIs\n\n| Export | Purpose |\n| ---------------------- | --------------------------------------------------------------- |\n| `resolveConflict` | Applies one current, incoming, or combined conflict resolution. |\n| `resolveRegion` | Resolves one parsed merge conflict region. |\n| `diffAcceptRejectHunk` | Applies accept or reject behavior to one change hunk. |\n\n## Annotation APIs\n\n| Export | Purpose |\n| ---------------------------- | ---------------------------------------------------------- |\n| `isFileAnnotation` | Tests whether one annotation targets a file line. |\n| `isDiffAnnotation` | Tests whether one annotation targets a diff side and line. |\n| `isFileAnnotationCollection` | Tests whether an array contains file annotations. |\n| `isDiffAnnotationCollection` | Tests whether an array contains diff annotations. |\n\n## File extension APIs\n\n| Export | Purpose |\n| ---------------------------- | ------------------------------------------------ |\n| `getFiletypeFromFileName` | Infers a language from a file name. |\n| `setCustomExtension` | Maps one file name or extension to a language. |\n| `replaceCustomExtensions` | Replaces all custom mappings. |\n| `getCustomExtensionsMap` | Gets a copy of custom mappings. |\n| `getCustomExtensionsVersion` | Gets the mapping revision. |\n| `EXTENSION_TO_FILE_FORMAT` | Maps built-in extensions and names to languages. |\n| `setLanguageOverride` | Assigns a language to parsed diff files. |\n","skills/diffs/references/api-editor.md":"# Editor API\n\nThis reference lists the primary exports from `@pierre/diffs/edit` and the\neditor APIs used by common integrations.\n\n## Exports\n\n| Export | Kind | Purpose |\n| --------------------------- | ----- | -------------------------------------------------------------- |\n| `CaretMetadata` | Type | Supplies the color shared by a remote caret and its highlight. |\n| `Editor` | Class | Adds text editing to a `File` or `FileDiff` instance. |\n| `EditorCaret` | Type | Describes an externally owned caret or highlighted selection. |\n| `EditStateManager` | Value | Manages keyed in-memory edit history and state. |\n| `ClearEditStateOptions` | Type | Selects retained state parts to clear. |\n| `EditState` | Type | Holds one complete live editing session. |\n| `EditorInitialState` | Type | Selects state fields to supply on first attachment. |\n| `EditorChange` | Type | Describes one normalized editor change. |\n| `EditorChangeEvent` | Type | Provides normalized edits and the current document. |\n| `EditorActiveLineOptions` | Type | Configures reveal behavior for an editor active line. |\n| `EditorEditCompleteEvent` | Type | Unites file and diff completion events for editor observation. |\n| `FileEditCompleteEvent` | Type | Describes a completed file edit session. |\n| `FileDiffEditCompleteEvent` | Type | Describes a completed diff edit session. |\n| `EditorCommand` | Type | Names an editor command. |\n| `EditorType` | Type | Selects a `file` or `file-diff` editor surface. |\n| `EditorFactory` | Type | Defines an editor-type-aware editor factory. |\n| `EditorFocusOptions` | Type | Selects a focus target and scroll behavior. |\n| `EditorKeymap` | Type | Defines ordered custom shortcut groups. |\n| `EditorOptions` | Type | Configures history, initial state, behavior, and events. |\n| `EditorShortcut` | Type | Defines one command shortcut. |\n| `EditorSelection` | Type | Adds caret direction to an editor range. |\n| `EditorViewState` | Type | Holds selections and editor-owned viewport offsets. |\n| `EditorViewportState` | Type | Holds horizontal and optional vertical scroll offsets. |\n| `KeyboardKey` | Type | Names a key accepted by an editor shortcut. |\n| `KeyboardModifier` | Type | Names a modifier accepted by an editor shortcut. |\n| `TextDocument` | Class | Stores text, positions, edits, search, and undo history. |\n| `TextDocumentChange` | Type | Describes the lines and characters changed by an edit. |\n| `Position` | Type | Identifies a zero-based line and character. |\n| `Range` | Type | Identifies a start and end position. |\n| `ResolvedTextEdit` | Type | Stores an edit with resolved document offsets. |\n| `SelectionDirection` | Type | Selects backward, neutral, or forward selection direction. |\n| `TextEdit` | Type | Replaces one range with new text. |\n| `Marker` | Type | Describes an editor diagnostic marker. |\n| `MarkerSeverity` | Type | Selects an editor marker severity. |\n\n## Lower-level exports\n\nThe edit entrypoint also exposes the state-management, keyboard-resolution,\nmarker-rendering, and popover-placement building blocks used by `Editor`.\n\n| Export | Kind | Purpose |\n| --------------------------------------- | -------- | --------------------------------------------------------------------- |\n| `ManagedEditSession` | Type | Selects mutable in-progress editor state by editor type. |\n| `ManagedFileEditSession` | Type | Holds mutable state for an active file editor session. |\n| `ManagedFileDiffEditSession` | Type | Holds mutable state for an active file-diff editor session. |\n| `cloneEditorViewState` | Function | Clones editor selections and viewport state. |\n| `toManagedEditState` | Function | Returns complete edit state when a managed session has required data. |\n| `resolveEditorCommandFromKeyboardEvent` | Function | Resolves a keyboard event through custom and default editor keymaps. |\n| `resolveFindAgainShortcut` | Function | Recognizes the next or previous native find shortcut. |\n| `MarkerRenderOptions` | Type | Supplies marker rendering, measurement, and popover dependencies. |\n| `MarkerRenderer` | Class | Renders marker ranges and marker hover popovers. |\n| `markerSeverityDatasetKey` | Function | Maps a marker severity to its DOM dataset key. |\n| `POPOVER_BOUNDARY_LINES` | Value | Sets the document-edge fallback threshold for popover placement. |\n| `POPOVER_FLIP_HYSTERESIS_PX` | Value | Sets the clearance required before a flipped popover returns. |\n| `PopoverPlacementBounds` | Type | Describes vertical popover placement bounds. |\n| `PopoverViewportBounds` | Type | Describes all visible viewport edges for popover clamping. |\n| `PopoverManagerOptions` | Type | Supplies active-popover state callbacks to `PopoverManager`. |\n| `PopoverManager` | Class | Tracks viewport geometry and stable popover placement. |\n| `setPopoverPositionStyles` | Function | Writes the CSS properties used to position and clamp a popover. |\n\n## `EditorOptions` fields\n\n| Field | Purpose |\n| ------------------------ | -------------------------------------------------------- |\n| `historyMaxEntries` | Limits the undo stack. |\n| `ownsVerticalViewport` | Opts into vertical scroll retention at construction. |\n| `initialState` | Supplies partial or complete state on first attach. |\n| `keymap` | Adds shortcut groups checked before the defaults. |\n| `roundedSelection` | Controls rounded selection corners. |\n| `matchBrackets` | Controls matching-bracket highlights. |\n| `autoSurround` | Controls quote and bracket insertion around a selection. |\n| `languageCommentConfig` | Overrides comment tokens by language. |\n| `enabledSelectionAction` | Enables the selection action surface. |\n| `clipboard` | Supplies a text clipboard reader. |\n| `renderSelectionAction` | Produces the selection action element. |\n| `renderCaret` | Produces an externally owned caret element. |\n| `onAttach` | Receives the editor and attached surface. |\n| `onChange` | Receives the event, including its editor instance. |\n| `onComplete` | Observes the completed file or diff event. |\n| `onFocus` | Runs after the editor gains focus. |\n| `onBlur` | Runs after the editor loses focus. |\n\nFor a `file-diff` editor, view-only `initialState` can omit document and diff\nmetadata. Transferring an edited document and its undo/redo history requires the\nmatching `document`, `fileInfo`, and `diffSession` from one complete\n`EditState`.\n\n`onComplete` receives the exact frozen event that is also passed to the\ncomponent's `onEditComplete` or CodeView's `onItemEditComplete`. The editor\nobserver runs first and still runs when the component callback is missing. You\ncannot accept or reject from this API. It is here for symmetry, but most\nintegrations should use those component callbacks instead.\n\nUse `editStateKey` for ordinary same-runtime restoration. It retains the draft,\nundo/redo history, selections, horizontal code scroll, eligible vertical scroll,\nand FileDiff resume metadata without an application synchronization loop. It is\nbounded in-memory state and does not survive a reload.\n\nUse `getViewState()` and `setViewState()` for an isolated selection/view copy or\ndurable application persistence. An attached surface reports horizontal\n`scrollLeft`. It reports `scrollTop` only when `ownsVerticalViewport: true` was\npassed to the constructor and the surface exclusively owns an element viewport.\nVirtualization alone does not imply ownership; page, ancestor, and CodeView\nshared scrolling remain application/viewer state.\n\n`getEditState()` exposes the raw objects from the latest complete edit-lifecycle\ncheckpoint. Checkpoints run after synchronization, document edits, explicit\n`setViewState()` calls, recycling, and completion. Selection or scroll movement\nalone does not update it; use `getViewState()` for an exact live copy. State\nremains available while rendering is recycled and during `onComplete`, and\nreturns `undefined` before synchronization or after completion. The result is\nborrowed editor-owned state rather than a serialization format.\n\n## `Editor` members\n\n| Member | Purpose |\n| -------------------------------------------------------- | ------------------------------------------------------- |\n| `new Editor(type, options?, editStateKey?)` | Creates an editor with optional keyed state retention. |\n| `type` | Identifies the editor as `file` or `file-diff`. |\n| `edit(instance)` | Attaches and returns the normal completion disposer. |\n| `setOptions(options)` | Merges editor options. |\n| `applyEdits(edits, updateHistory?)` | Applies programmatic text edits. |\n| `canUndo` | Reports whether undo has an entry. |\n| `canRedo` | Reports whether redo has an entry. |\n| `undo()` | Reverts the latest edit. |\n| `redo()` | Reapplies the latest reverted edit. |\n| `getFile()` | Gets the current file contents. |\n| `getText()` | Gets the current text. |\n| `getViewState()` | Gets selections and editor-owned view state. |\n| `setViewState(state)` | Sets selections and editor-owned view state. |\n| `getEditState()` | Gets the latest edit-lifecycle state checkpoint. |\n| `setSelections(selections)` | Sets directed selection ranges. |\n| `setCarets(carets)` | Replaces the externally owned caret and highlight list. |\n| `setMarkers(markers)` | Sets diagnostic markers. |\n| `focus(options?)` | Focuses the editor. |\n| `blur()` | Removes editor focus. |\n| `cleanUp(reason?: 'discard' \\| 'recycle' \\| 'complete')` | Suspends rendering or completes the editing session. |\n\n`editStateKey` opts an editor into retained in-memory sessions across editor\ninstances. File and file-diff namespaces are independent and each keeps up to\n100 inactive entries by default. The same type/key cannot be active in two\neditors at once.\n\nCall the disposer returned by `edit(instance)` for the normal session-ending\npath; it is equivalent to `cleanUp('complete')` and installs an accepted\ncompletion result. `cleanUp('discard')` still publishes the completion event but\ndoes not install its result. `cleanUp('recycle')` suspends rendering without\nending the session or changing the editor-component association. Calling\n`edit(instance)` again resumes rendering for that same component.\n\n## `EditStateManager` members\n\n| Member | Purpose |\n| ----------------------------------- | --------------------------------------------------------------- |\n| `get(type, editStateKey)` | Borrows active or inactive complete state without touching LRU. |\n| `clear(type, editStateKey, parts?)` | Clears inactive complete or granular state. |\n| `clearAll()` | Clears all inactive state without mutating active editors. |\n| `setCapacity(capacity)` | Sets each namespace's inactive retained-state capacity. |\n\n`clear()` returns `false` for active or missing state. Omit `parts` to remove\nthe complete entry. `{ document: true }` also removes the complete entry because\nall other parts depend on it. Use `{ history: true }`, `{ selections: true }`,\n`{ view: true }`, or `{ editor: true }` to keep the document while clearing undo\nhistory, cursor state, scroll state, or both view-state parts respectively.\n\nFor durable persistence, store `FileContents` and optional JSON-safe\n`EditorViewState` separately, then construct a fresh `TextDocument` when\nrestoring. Complete `EditState` and undo/redo history are not serialization\ncontracts.\n\n## `TextDocument` members\n\n| Member | Purpose |\n| ---------------------------------------------------- | ----------------------------------------------------- |\n| `new TextDocument(uri, text, languageId?, version?)` | Creates a text document. |\n| `uri` | Gets the document identifier. |\n| `languageId` | Gets the language identifier. |\n| `version` | Gets the document version. |\n| `lineCount` | Gets the line count. |\n| `eol` | Gets the line-ending sequence. |\n| `canUndo` | Reports whether undo has an entry. |\n| `canRedo` | Reports whether redo has an entry. |\n| `positionAt(offset)` | Converts an offset to a position. |\n| `positionsAt(offsets)` | Converts several offsets to positions. |\n| `offsetAt(position)` | Converts a position to an offset. |\n| `getText(range?)` | Gets all text or one range. |\n| `getLineText(line, includeLineBreak?)` | Gets one line. |\n| `normalizeEol(text)` | Converts text to the document line ending. |\n| `getLineLength(line, includeLineBreak?)` | Gets one line length. |\n| `charAt(offsetOrPosition)` | Gets one character. |\n| `getTextSlice(start, end)` | Gets text between two offsets. |\n| `findNextNonOverlappingSubstring(needle, occupied)` | Finds an unused substring range. |\n| `search(params)` | Finds text ranges. |\n| `applyEdits(edits, ...)` | Resolves and applies position-based edits. |\n| `resolveEdits(edits)` | Converts position-based edits to offset edits. |\n| `applyResolvedEdits(edits, ...)` | Applies offset-based edits. |\n| `setLastUndoSelectionsAfter(selections)` | Associates selections with the latest history entry. |\n| `setLastUndoLineAnnotations(before, after)` | Associates annotations with the latest history entry. |\n| `undo()` | Reverts one document history entry. |\n| `redo()` | Reapplies one document history entry. |\n| `normalizePosition(position)` | Clamps a position to the document. |\n","skills/diffs/references/api-highlighting.md":"# Highlighting API\n\n`preferredHighlighter` selects `'shiki-js'` (default), `'shiki-wasm'`, or\n`'highlights'`. Backends load lazily. File, FileDiff, Editor, FileStream, SSR\npreload options, and worker highlighter options accept this selection.\n\nOnly one backend type can be loaded per JavaScript realm (page, worker, or SSR\nprocess). Requests without `preferredHighlighter` use the loaded type, else\n`'shiki-js'`. Shared-highlighter requests (components, `getSharedHighlighter`,\n`preloadHighlighter`) keep using the loaded type even when they name another\none; they do not throw. `createHighlighter` with another type throws. To switch\ntypes, dispose every instance of the loaded type, shared or from\n`createHighlighter`. `getHighlighterType()` returns the loaded type.\n\n## Shared highlighter\n\n```ts\nimport { getSharedHighlighter } from '@pierre/diffs';\n\nconst highlighter = await getSharedHighlighter({\n preferredHighlighter: 'highlights',\n themes: ['pierre-dark'],\n langs: ['typescript'],\n});\nconst html = highlighter.codeToHtml('const value = 1;', {\n lang: 'typescript',\n theme: 'pierre-dark',\n});\n```\n\n`DiffsHighlighter` is an abstract class with `name`, `themeResolver`,\n`getTheme`, `codeToHtml`, `codeToTokens`, `createEditorTokenizer`,\n`createStreamTokenizer`, `loadLanguages`, `hasLoadedLanguages`,\n`attachLanguages`, and `dispose`. Highlights bundles its lexers, so its language\nmethods do nothing and `hasLoadedLanguages` is true until disposal. Import\nbackend-specific Shiki APIs and types from `shiki` directly.\n\n| Export | Purpose |\n| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |\n| `getSharedHighlighter` | Gets or creates the shared instance and loads themes/languages. |\n| `createHighlighter` | Creates an independently disposable instance: `createHighlighter('highlights')`. |\n| `getHighlighterType` | Returns the backend type loaded in this realm, if any. |\n| `preloadHighlighter` | Loads the same settings before a render. |\n| `getHighlighterIfLoaded` | Gets the loaded shared instance when its requested settings are available. |\n| `isHighlighterLoaded`, `isHighlighterLoading`, `isHighlighterNull` | Inspect shared state without arguments. Use `getHighlighterIfLoaded()` to obtain a ready instance. |\n| `disposeHighlighter` | Disposes the shared instance and clears resolved caches; retained `createHighlighter` instances keep their themes. |\n| `getHighlighterOptions` | Converts component options to highlighter input. |\n| `getHighlighterThemeStyles` | Creates component CSS from a loaded theme. |\n| `getThemes` | Converts a theme name or light/dark pair to a name list. |\n\n## Themes\n\n`DiffsTheme` contains `name`, `type`, `fg`, `bg`, optional editor `colors`, and\nbackend syntax data: `textmate` for Shiki and `zed` for Highlights. Bundled\nPierre and Shiki theme names also resolve to bundled Highlights palettes.\n\n| Export | Purpose |\n| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |\n| `registerCustomTheme(name, loader, type = 'textmate')` | Registers a loader with type `'textmate'` for Shiki, `'zed'` for Highlights, or `'diffs'` for portable themes. |\n| `createCSSVariablesTheme` | Creates a portable palette; accepts name, variablePrefix (default `--diffs-`), variableDefaults, and fontStyle. |\n| `registerCustomCSSVariableTheme` | Preserves `(name, variableDefaults, fontStyle = false)` and the `--diffs-` prefix. |\n| `resolveTheme`, `resolveThemes` | Resolve themes; optional second argument selects the backend. |\n| `getResolvedOrResolveTheme`, `getResolvedThemes`, `hasResolvedThemes` | Read or populate the selected backend's cache. |\n| `attachResolvedThemes` | Seeds resolved themes into a highlighter, including worker instances. |\n| `areThemesAttached` | Checks cached themes; optionally takes a backend name or highlighter. |\n| `cleanUpResolvedThemes` | Clears caches, preserving registrations. |\n\n`createCSSVariablesTheme` previously re-exported Shiki's\n`createCssVariablesTheme`, whose default prefix is `--shiki-` and whose result\nis a raw Shiki registration. Pass `variablePrefix: '--shiki-'` to keep\nstylesheets written for that default, or import Shiki's helper directly when a\nraw registration is needed.\n\nLoaders return a theme directly or as a module's `default` export. Register one\nloader per name and type; explicit TextMate or Zed loaders take priority over a\nshared Diffs loader. TextMate and Diffs names must match the registration. Zed\nthemes use the registered name instead of their display name; a `ThemeFamily`\nuses its first member unless the loader selects another.\n\nResolve themes on the main thread before passing them to workers. For one theme\nacross backends, use `createCSSVariablesTheme` or a `DiffsTheme` containing both\n`textmate` (Shiki's normalized `ThemeRegistrationResolved`) and `zed` palettes.\n\n## Languages\n\n`registerCustomLanguage(name, loader, extensions?)` registers TextMate grammars\nfor Shiki. Highlights includes its supported lexers and ignores custom grammar\nregistrations. Explicit unknown languages fall back to plain text in Highlights.\n\n`resolveLanguage(s)`, `getResolvedLanguages`, `hasResolvedLanguages`,\n`getResolvedOrResolveLanguage`, `attachResolvedLanguages`,\n`areLanguagesAttached`, and `cleanUpResolvedLanguages` support Shiki grammar\nloading. Language loader/cache maps remain available for compatibility.\n\n## Rendering and streams\n\n`renderFileWithHighlighter` and `renderDiffWithHighlighter` create component\nsyntax trees from backend-independent tokens.\n\nUse `highlighter.createStreamTokenizer(options)` for incremental append-only\ninput and `highlighter.createEditorTokenizer(options)` for document editing.\n`FileStream` connects a readable code stream through `setup(source, wrapper)`,\naccepts `preferredHighlighter`, supports `setThemeType`, and releases its stream\nthrough `cleanUp()`.\n","skills/diffs/references/api-react.md":"# React API\n\nThis reference lists the React-specific exports from `@pierre/diffs/react`. The\nentry also re-exports every type in [Shared types](api-types.md).\n\n## Components and hooks\n\n| Export | Kind | Purpose |\n| --------------------------- | --------- | --------------------------------------------------------- |\n| `File` | Component | Renders one code file. |\n| `FileDiff` | Component | Renders pre-parsed diff metadata. |\n| `MultiFileDiff` | Component | Parses and renders an old and new file pair. |\n| `PatchDiff` | Component | Parses and renders one unified patch string. |\n| `UnresolvedFile` | Component | Renders and resolves merge conflicts in one file. |\n| `CodeView` | Component | Renders a virtualized list of files and diffs. |\n| `Virtualizer` | Component | Provides simple viewport virtualization. |\n| `useVirtualizer` | Hook | Gets the nearest simple `Virtualizer` instance. |\n| `EditProvider` | Component | Supplies an editor factory. |\n| `useCreateEditor` | Hook | Gets the nearest editor factory. |\n| `WorkerPoolContextProvider` | Component | Creates and supplies a worker pool. |\n| `useWorkerPool` | Hook | Gets the nearest worker pool. |\n| `useFileInstance` | Hook | Creates and manages a vanilla `File` instance. |\n| `useFileDiffInstance` | Hook | Creates and manages a vanilla `FileDiff` instance. |\n| `useStableCallback` | Hook | Returns a stable callback that reads the latest function. |\n\n## Component and provider types\n\n| Export | Purpose |\n| ----------------------------------- | ----------------------------------------------------------------- |\n| `FileProps` | Defines props for `File`. |\n| `FileOptions` | Defines vanilla file options and the React `options` prop. |\n| `FileDiffProps` | Defines props for `FileDiff`. |\n| `MultiFileDiffProps` | Defines props for `MultiFileDiff`. |\n| `PatchDiffProps` | Defines props for `PatchDiff`. |\n| `UnresolvedFileProps` | Defines props for `UnresolvedFile`. |\n| `UnresolvedFileReactOptions` | Defines merge-conflict options for React. |\n| `DiffBasePropsReact` | Defines props shared by React diff components. |\n| `CodeViewProps` | Defines controlled or uncontrolled `CodeView` props. |\n| `ControlledCodeViewProps` | Defines `CodeView` props with `items`. |\n| `UncontrolledCodeViewProps` | Defines `CodeView` props with `initialItems`. |\n| `CodeViewReactOptions` | Defines the React-safe `CodeView` option set. |\n| `CodeViewHandle` | Defines imperative list, selection, scroll, and editor controls. |\n| `EditorFactory` | Re-exports the editor factory type from `@pierre/diffs/edit`. |\n| `EditProviderProps` | Defines the type-aware `EditProvider` factory prop. |\n| `MergeConflictActionsTypeOption` | Selects no actions, default actions, or a custom action renderer. |\n| `RenderMergeConflictActionContext` | Supplies conflict resolution to a custom action renderer. |\n| `RenderMergeConflictActions` | Defines a custom conflict action renderer. |\n| `WorkerInitializationRenderOptions` | Defines initial worker languages and render options. |\n| `WorkerPoolOptions` | Defines the worker factory, pool size, and cache size. |\n\n## Contexts and render helpers\n\n| Export | Kind | Purpose |\n| ------------------------- | -------- | ------------------------------------------------------ |\n| `EditContext` | Context | Holds the editor factory. |\n| `WorkerPoolContext` | Context | Holds the worker pool. |\n| `VirtualizerContext` | Context | Holds the simple virtualizer. |\n| `GutterUtilitySlotStyles` | Value | Supplies style keys for gutter utility slots. |\n| `MergeConflictSlotStyles` | Value | Supplies style keys for merge conflict slots. |\n| `noopRender` | Function | Returns no React output for an optional render slot. |\n| `renderDiffChildren` | Function | Builds React portals for diff slots. |\n| `renderFileChildren` | Function | Builds React portals for file slots. |\n| `templateRender` | Function | Renders React content through a managed template slot. |\n","skills/diffs/references/api-rendering.md":"# Low-level rendering API\n\nThis reference lists the renderer, manager, DOM helper, comparison, and constant\nexports from `@pierre/diffs`.\n\n## Contents\n\n- [Renderers](#renderers)\n- [Interaction manager](#interaction-manager)\n- [Size, scroll, and render managers](#size-scroll-and-render-managers)\n- [Comparison helpers](#comparison-helpers)\n- [Syntax tree and DOM helpers](#syntax-tree-and-dom-helpers)\n- [Layout and CSS helpers](#layout-and-css-helpers)\n- [Constants](#constants)\n\n## Renderers\n\n| Export | Kind | Purpose |\n| -------------------------------------- | ----- | ------------------------------------------------------- |\n| `FileRenderer` | Class | Converts one file to highlighted HAST, CSS, and HTML. |\n| `FileRendererOptions` | Type | Adds header mode to base code options. |\n| `FileRenderResult` | Type | Holds file HAST, CSS, row counts, and buffers. |\n| `DiffHunksRenderer` | Class | Converts diff hunks to highlighted column HAST and CSS. |\n| `DiffHunksRendererOptions` | Type | Configures one hunk renderer. |\n| `DiffHunksRendererOptionsWithDefaults` | Type | Describes resolved hunk renderer options. |\n| `HunksRenderResult` | Type | Holds rendered diff columns, metadata, and row count. |\n| `RenderedLineContext` | Type | Supplies line state to a line decoration. |\n| `LineDecoration` | Type | Defines a custom line wrapper and injected rows. |\n| `InjectedRow` | Type | Defines one row inserted around a unified line. |\n| `SplitInjectedRow` | Type | Defines one row inserted around a split line. |\n| `UnifiedInjectedRowPlacement` | Type | Selects placement before or after a unified row. |\n| `SplitInjectedRowPlacement` | Type | Selects side and placement for a split row. |\n| `UnifiedLineDecorationProps` | Type | Supplies one unified row to a decoration. |\n| `SplitLineDecorationProps` | Type | Supplies paired split rows to a decoration. |\n\n## Interaction manager\n\n| Export | Kind | Purpose |\n| ------------------------------- | -------- | ------------------------------------------------------------------------ |\n| `InteractionManager` | Class | Handles hover, token, gutter, and line selection events. |\n| `InteractionManagerMode` | Type | Selects file or diff interaction data. |\n| `InteractionManagerBaseOptions` | Type | Defines interaction callbacks and enabled features. |\n| `InteractionManagerOptions` | Type | Adds required DOM access to base interaction options. |\n| `GetHoveredLineResult` | Type | Describes the current hovered file or diff line. |\n| `GetLineIndexUtility` | Type | Maps a logical line to row and column indexes. |\n| `OnLineClickProps` | Type | Describes a file line click. |\n| `OnLineEnterLeaveProps` | Type | Describes file line pointer entry or exit. |\n| `OnDiffLineClickProps` | Type | Describes a diff line click. |\n| `OnDiffLineEnterLeaveProps` | Type | Describes diff line pointer entry or exit. |\n| `OnTokenEventProps` | Type | Selects file or diff token event data. |\n| `SelectionWriteOptions` | Type | Configures callback emission, the active side, and line-only highlights. |\n| `MergeConflictActionTarget` | Type | Describes a merge conflict action element. |\n| `LogTypes` | Type | Selects interaction log categories. |\n| `pluckInteractionOptions` | Function | Selects interaction fields from component options. |\n\n## Size, scroll, and render managers\n\n| Export | Kind | Purpose |\n| --------------------------------- | -------- | ------------------------------------------------------------- |\n| `ResizeManager` | Class | Measures rows, annotations, and column CSS values. |\n| `ResizeManagerColumnVariableMode` | Type | Selects column variable measurement or application. |\n| `ResizeManagerSetupOptions` | Type | Configures annotation and column measurement. |\n| `ScrollSyncManager` | Class | Synchronizes additions and deletions column scroll positions. |\n| `queueRender` | Function | Adds a callback to the shared animation render queue. |\n| `dequeueRender` | Function | Removes a callback from the shared render queue. |\n| `clearRenderQueue` | Function | Removes all callbacks from the shared render queue. |\n\n## Comparison helpers\n\n| Export | Purpose |\n| ----------------------------- | ------------------------------------------------- |\n| `areDiffLineAnnotationsEqual` | Compares two diff annotation arrays. |\n| `areLineAnnotationsEqual` | Compares two file annotation arrays. |\n| `areDiffRenderOptionsEqual` | Compares resolved diff render options. |\n| `areFileRenderOptionsEqual` | Compares resolved file render options. |\n| `areDiffTargetsEqual` | Compares two diff interaction targets. |\n| `areFilesEqual` | Compares two file inputs. |\n| `areHunkDataEqual` | Compares two hunk data objects. |\n| `areObjectsEqual` | Performs the package's shallow object comparison. |\n| `areOptionsEqual` | Compares component option objects. |\n| `arePrePropertiesEqual` | Compares calculated `pre` properties. |\n| `areRenderRangesEqual` | Compares two render ranges. |\n| `areSelectionsEqual` | Compares editor selection arrays. |\n| `areThemesEqual` | Compares theme names or light/dark pairs. |\n| `areVirtualWindowSpecsEqual` | Compares two virtual window descriptions. |\n| `areWorkerStatsEqual` | Compares two worker statistics objects. |\n\n## Syntax tree and DOM helpers\n\n| Export | Kind | Purpose |\n| -------------------------------- | -------- | ---------------------------------------------------------- |\n| `createAnnotationElement` | Function | Creates a HAST annotation row from an annotation span. |\n| `createAnnotationWrapperNode` | Function | Creates a DOM host for an annotation slot. |\n| `createDiffSpanDecoration` | Function | Creates one inline diff decoration. |\n| `pushOrJoinSpan` | Function | Adds or joins one inline diff span. |\n| `createEmptyRowBuffer` | Function | Creates an empty virtual row buffer. |\n| `createFileHeaderElement` | Function | Creates a file or diff header HAST element. |\n| `CreateFileHeaderElementProps` | Type | Defines header source, mode, and sticky state. |\n| `createGutterGap` | Function | Creates a gutter gap HAST element. |\n| `createGutterItem` | Function | Creates a gutter item HAST element. |\n| `createGutterWrapper` | Function | Creates a gutter wrapper HAST element. |\n| `createGutterUtilityElement` | Function | Creates a gutter utility HAST element. |\n| `createGutterUtilityContentNode` | Function | Creates a gutter utility DOM content host. |\n| `createHastElement` | Function | Creates a typed HAST element. |\n| `createIconElement` | Function | Creates a sprite icon HAST element. |\n| `createTextNodeElement` | Function | Creates a HAST text node. |\n| `createNoNewlineElement` | Function | Creates the missing-final-newline HAST element. |\n| `createPreElement` | Function | Creates the outer HAST `pre` element. |\n| `createPreWrapperProperties` | Function | Creates HAST properties for a `pre` wrapper. |\n| `createRowNodes` | Function | Creates DOM row and content elements for one line. |\n| `createSeparator` | Function | Creates a hunk separator HAST element. |\n| `createSpanFromToken` | Function | Creates a HAST span from one highlighted token. |\n| `createStyleElement` | Function | Creates a DOM style element with an attribute marker. |\n| `createThemeStyleElement` | Function | Creates a marked theme style element. |\n| `createUnsafeCSSStyleNode` | Function | Creates a marked custom CSS style element. |\n| `findCodeElement` | Function | Finds the code element in a HAST tree. |\n| `getLineNodes` | Function | Gets rendered line nodes from a HAST root. |\n| `getOrCreateCodeNode` | Function | Reuses or creates a code column DOM node. |\n| `getLineAnnotationName` | Function | Creates the slot name for a line annotation. |\n| `getHunkSeparatorSlotName` | Function | Creates the slot name for a hunk separator. |\n| `getIconForType` | Function | Maps a file change type to a sprite icon. |\n| `processLine` | Function | Applies line render state to one HAST line. |\n| `setPreNodeProperties` | Function | Applies resolved render properties to a DOM `pre` element. |\n| `prerenderHTMLIfNecessary` | Function | Adds preloaded HTML to an empty host element. |\n\n## Layout and CSS helpers\n\n| Export | Purpose |\n| -------------------------------- | ------------------------------------------------------------- |\n| `createWindowFromScrollPosition` | Calculates a virtual window from scroll measurements. |\n| `isDefaultRenderRange` | Tests whether a render range covers the default full range. |\n| `prefersReducedMotion` | Reads the reduced-motion media preference. |\n| `formatCSSVariablePrefix` | Creates the global or token CSS variable prefix. |\n| `wrapCoreCSS` | Places core CSS in its cascade layer. |\n| `wrapThemeCSS` | Places theme CSS in its layer and mode selector. |\n| `wrapUnsafeCSS` | Places custom CSS in its cascade layer. |\n| `patchScrollbarGutterSize` | Updates the measured scrollbar gutter in theme CSS. |\n| `detachString` | Copies a retained substring to an independent backing string. |\n| `releaseStringDetachBuffer` | Resets the reusable string copy buffer. |\n| `SVGSpriteSheet` | Contains the SVG symbols used by rendered controls. |\n| `SVGSpriteNames` | Names a symbol in `SVGSpriteSheet`. |\n\n## Constants\n\n| Export | Purpose |\n| ------------------------------------------ | ----------------------------------------------------- |\n| `DEFAULT_THEMES` | Provides the default light and dark theme names. |\n| `DEFAULT_TOKENIZE_MAX_LENGTH` | Provides the default total tokenization limit. |\n| `DEFAULT_COLLAPSED_CONTEXT_THRESHOLD` | Provides the default hidden-context threshold. |\n| `DEFAULT_EXPANDED_REGION` | Provides the default hunk expansion state. |\n| `DEFAULT_RENDER_RANGE` | Provides the full render range. |\n| `EMPTY_RENDER_RANGE` | Provides an empty render range. |\n| `DEFAULT_VIRTUAL_FILE_METRICS` | Provides estimated file header and line heights. |\n| `DEFAULT_CODE_VIEW_FILE_METRICS` | Provides list item height estimates. |\n| `DEFAULT_CODE_VIEW_LAYOUT` | Provides an empty list layout. |\n| `DEFAULT_SMOOTH_SCROLL_SETTINGS` | Provides the default smooth scroll settings. |\n| `DIFFS_TAG_NAME` | Provides the `diffs-container` custom element name. |\n| `CORE_CSS_ATTRIBUTE` | Provides the core style marker attribute. |\n| `THEME_CSS_ATTRIBUTE` | Provides the theme style marker attribute. |\n| `UNSAFE_CSS_ATTRIBUTE` | Provides the custom style marker attribute. |\n| `DIFFS_SCROLLBAR_MEASURE_ATTRIBUTE` | Provides the scrollbar measurement attribute. |\n| `DIFFS_SCROLLBAR_GUTTER_MEASURED_PROPERTY` | Provides the measured scrollbar CSS property. |\n| `CODE_VIEW_HEADER_ATTRIBUTE` | Provides the list header host attribute. |\n| `CODE_VIEW_FOOTER_ATTRIBUTE` | Provides the list footer host attribute. |\n| `CUSTOM_HEADER_SLOT_ID` | Provides the custom header slot ID. |\n| `HEADER_PREFIX_SLOT_ID` | Provides the header prefix slot ID. |\n| `HEADER_FILENAME_SUFFIX_SLOT_ID` | Provides the filename suffix slot ID. |\n| `HEADER_METADATA_SLOT_ID` | Provides the header metadata slot ID. |\n| `HUNK_HEADER` | Provides the patch hunk header marker. |\n| `FILE_CONTEXT_BLOB` | Matches a patch hunk boundary. |\n| `INDEX_LINE_METADATA` | Provides the patch index metadata marker. |\n| `COMMIT_METADATA_SPLIT` | Provides the commit metadata separator expression. |\n| `FILENAME_HEADER_REGEX` | Matches a standard patch file header. |\n| `GIT_DIFF_FILE_BREAK_REGEX` | Matches a Git patch file boundary. |\n| `UNIFIED_DIFF_FILE_BREAK_REGEX` | Matches a unified patch file boundary. |\n| `MERGE_CONFLICT_START_MARKER_REGEX` | Matches a conflict start marker. |\n| `MERGE_CONFLICT_BASE_MARKER_REGEX` | Matches a conflict base marker. |\n| `MERGE_CONFLICT_SEPARATOR_MARKER_REGEX` | Matches a conflict separator marker. |\n| `MERGE_CONFLICT_END_MARKER_REGEX` | Matches a conflict end marker. |\n| `SPLIT_WITH_NEWLINES` | Splits text while it preserves newline tokens. |\n| `DIFFS_DEVELOPMENT_BUILD` | Reports whether the package uses a development build. |\n","skills/diffs/references/api-ssr.md":"# SSR API\n\nThis reference lists the SSR-specific exports from `@pierre/diffs/ssr`. The\nentry also re-exports every type in [Shared types](api-types.md).\n\n## Functions\n\n| Export | Purpose |\n| --------------------------- | ------------------------------------------------------------- |\n| `preloadFile` | Renders one file and returns props with `prerenderedHTML`. |\n| `preloadFileDiff` | Renders pre-parsed diff metadata and returns component props. |\n| `preloadMultiFileDiff` | Parses and renders an old and new file pair. |\n| `preloadPatchDiff` | Parses and renders one patch for `PatchDiff`. |\n| `preloadPatchFile` | Parses a multi-file patch and returns one result per file. |\n| `preloadUnresolvedFile` | Renders one merge-conflict file and returns component props. |\n| `preloadDiffHTML` | Renders a diff directly to an HTML string. |\n| `preloadUnresolvedFileHTML` | Renders a merge-conflict file directly to an HTML string. |\n| `renderHTML` | Serializes rendered HAST elements to HTML. |\n\n## Types\n\n| Export | Purpose |\n| ------------------------------ | -------------------------------------------------------- |\n| `PreloadFileOptions` | Defines input for `preloadFile`. |\n| `PreloadedFileResult` | Adds `prerenderedHTML` to file input. |\n| `PreloadDiffOptions` | Defines parsed or file-pair input for `preloadDiffHTML`. |\n| `PreloadFileDiffOptions` | Defines input for `preloadFileDiff`. |\n| `PreloadFileDiffResult` | Adds `prerenderedHTML` to parsed diff input. |\n| `PreloadMultiFileDiffOptions` | Defines input for `preloadMultiFileDiff`. |\n| `PreloadMultiFileDiffResult` | Adds `prerenderedHTML` to file-pair input. |\n| `PreloadPatchDiffOptions` | Defines input for `preloadPatchDiff`. |\n| `PreloadPatchDiffResult` | Adds `prerenderedHTML` to patch input. |\n| `PreloadPatchFileOptions` | Defines input for `preloadPatchFile`. |\n| `PreloadUnresolvedFileOptions` | Defines input for `preloadUnresolvedFile`. |\n| `PreloadUnresolvedFileResult` | Adds `prerenderedHTML` to merge-conflict input. |\n","skills/diffs/references/api-types.md":"# Shared types\n\nThis reference lists every export from the shared `@pierre/diffs` type module.\nThe root, React, and SSR entries re-export these types.\n\n## Contents\n\n- [Files and patches](#files-and-patches)\n- [Themes and options](#themes-and-options)\n- [Annotations and selection](#annotations-and-selection)\n- [`CodeView` types](#codeview-types)\n- [Lines, hunks, and render state](#lines-hunks-and-render-state)\n- [Render results and virtualization](#render-results-and-virtualization)\n- [Tokenization and diff types](#tokenization-and-diff-types)\n\n## Files and patches\n\n| Export | Purpose |\n| ------------------------------- | ----------------------------------------------------------------- |\n| `FileContents` | Describes a file name, text, language, header, and cache key. |\n| `DiffFileInput` | Accepts an old and new file for changes, additions, or deletions. |\n| `MaybeDiffFileInput` | Accepts a file pair or no file input. |\n| `FileDiffContentsLoader` | Loads complete files for partial diff metadata. |\n| `FileDiffLoadedChangedFiles` | Returns both files for a loaded changed diff. |\n| `FileDiffLoadedPureRenamedFile` | Returns the new file for a loaded pure rename. |\n| `FileDiffLoadedFiles` | Represents either loaded-file result. |\n| `ChangeTypes` | Names changed, renamed, added, or deleted file states. |\n| `ParsedPatch` | Holds patch metadata and parsed files. |\n| `ContextContent` | Describes one unchanged hunk block. |\n| `ChangeContent` | Describes one additions and deletions block. |\n| `Hunk` | Describes one parsed patch hunk. |\n| `FileDiffMetadata` | Holds parsed file names, lines, hunks, and change metadata. |\n| `MergeConflictMarkerRowType` | Names a merge conflict marker row. |\n| `MergeConflictMarkerRow` | Describes one marker row and its source line. |\n| `MergeConflictRegion` | Describes one parsed merge conflict region. |\n| `MergeConflictResolution` | Selects current, incoming, or both conflict contents. |\n| `MergeConflictActionPayload` | Describes one conflict action and region. |\n| `ProcessFileConflictData` | Holds state while patch parsing processes conflicts. |\n| `ConflictResolverTypes` | Names current, incoming, or both conflict choices. |\n\n## Themes and options\n\n| Export | Purpose |\n| ------------------------------------ | -------------------------------------------------------------- |\n| `SupportedLanguages` | Accepts a bundled, text, ANSI, or custom language name. |\n| `HighlighterTypes` | Selects shiki-js, shiki-wasm, or highlights. |\n| `HighlightedToken` | Stores a character index, foreground, and token text. |\n| `DiffsThemeNames` | Accepts a bundled or custom theme name. |\n| `ThemesType` | Maps light and dark schemes to theme names. |\n| `ThemeTypes` | Selects system, light, or dark mode. |\n| `DiffsHighlighter` | Defines backend-independent tokenization and theme resolution. |\n| `BaseCodeOptions` | Configures themes, wrapping, headers, tokenization, and CSS. |\n| `BaseDiffOptions` | Adds layout, indicators, context, and line diff options. |\n| `BaseDiffOptionsWithDefaults` | Describes required diff options after defaults apply. |\n| `DiffIndicators` | Selects classic, bar, or hidden diff indicators. |\n| `HunkSeparators` | Selects the hunk separator presentation. |\n| `LineDiffTypes` | Selects word, alternate word, character, or no inline diff. |\n| `FileHeaderRenderMode` | Selects a default or custom file header. |\n| `CustomPreProperties` | Defines custom properties for the rendered `pre` element. |\n| `PrePropertiesConfig` | Describes calculated `pre` element properties. |\n| `ExtensionFormatMap` | Maps file names or extensions to languages. |\n| `RenderHeaderPrefixCallback` | Produces prefix content for a diff header. |\n| `RenderHeaderFilenameSuffixCallback` | Produces filename suffix content for a diff header. |\n| `RenderHeaderMetadataCallback` | Produces metadata content for a diff header. |\n| `RenderFileMetadata` | Produces header content for a file. |\n| `PostRenderPhase` | Names mount, update, or unmount callback phases. |\n\n## Annotations and selection\n\n| Export | Purpose |\n| -------------------- | ----------------------------------------------------- |\n| `AnnotationSide` | Selects deletions or additions for an annotation. |\n| `LineAnnotation` | Associates metadata with one file line. |\n| `DiffLineAnnotation` | Associates metadata with one side and line. |\n| `AnnotationLineMap` | Groups diff annotations by line number. |\n| `SelectedLineRange` | Describes a selected start and end across diff sides. |\n| `SelectionSide` | Selects deletions or additions for a selection. |\n| `SelectionPoint` | Describes one line and optional side. |\n\n## `CodeView` types\n\n| Export | Purpose |\n| --------------------------------- | -------------------------------------------------------- |\n| `CodeViewFileItem` | Describes one file item in a virtualized list. |\n| `CodeViewDiffItem` | Describes one diff item in a virtualized list. |\n| `CodeViewItem` | Represents a file or diff list item. |\n| `CodeViewCreateEditorOptions` | Provides CodeView's routed editor option subset. |\n| `CodeViewItemEditCompleteHandler` | Handles completion with correlated event and item types. |\n| `CodeViewScrollBehavior` | Selects instant, smooth, or automatic smooth scroll. |\n| `CodeViewScrollTarget` | Represents any supported list scroll target. |\n| `CodeViewPositionScrollTarget` | Scrolls to an absolute list position. |\n| `CodeViewLineScrollTarget` | Scrolls to one item line. |\n| `CodeViewRangeScrollTarget` | Scrolls to one item line range. |\n| `CodeViewItemScrollTarget` | Scrolls to one item boundary. |\n| `NumericScrollLineAnchor` | Describes a numeric position inside a line. |\n| `CodeViewLayout` | Stores item offsets, heights, and total list height. |\n| `PendingCodeViewLayoutReset` | Describes a deferred list layout reset. |\n| `SmoothScrollSettings` | Configures duration and distance for smooth list scroll. |\n\n`CodeViewCreateEditorOptions` currently contains the routed `onChange(event)`\ncallback that `CodeView` uses to emit `onItemEditChange(event, item)`; it does\nnot add an item ID. A `CodeViewOptions.createEditor` factory also receives the\noptional `editStateKey` returned by `getEditStateKey(item)` as its third\nargument. Forward that key separately to the editor constructor. It retains the\neditable draft, undo/redo history, selections, and horizontal code scroll. Item\neditors never own CodeView's shared vertical position.\n\n`onItemEditComplete(event, item, nextItem)` must return `'accept'` to accept the\ncompleted item or `'reject'` to restore the original while the item remains\npresent; a missing callback rejects. During removal or teardown, neither\ndecision reinserts the item. Controlled owners must put the supplied `nextItem`\ninto their item state when accepting an item that should remain. If the item\nuses keyed render caching, assigning a fresh `cacheKey` to the accepted event\nfile or diff invalidates that cache.\n\n## Lines, hunks, and render state\n\n| Export | Purpose |\n| ---------------------------- | --------------------------------------------------------------- |\n| `HunkLineType` | Names context, expanded, addition, deletion, or metadata lines. |\n| `HunkData` | Describes one hunk's render indexes and line ranges. |\n| `HunkExpansionRegion` | Describes expanded context above and below a hunk. |\n| `ExpansionDirections` | Selects up, down, or both expansion directions. |\n| `DiffAcceptRejectHunkType` | Selects accept, reject, or both hunk controls. |\n| `DiffAcceptRejectHunkConfig` | Configures hunk accept and reject behavior. |\n| `GapSpan` | Describes an empty row span. |\n| `AnnotationSpan` | Describes an annotation row span. |\n| `LineSpans` | Represents a gap or annotation span. |\n| `LineTypes` | Names rendered context and change line classes. |\n| `LineInfo` | Describes a rendered line number, side, and type. |\n| `CodeColumnType` | Selects unified, additions, or deletions columns. |\n| `LineEventBaseProps` | Supplies a file line to an interaction callback. |\n| `DiffLineEventBaseProps` | Supplies a diff line and side to an interaction callback. |\n| `TokenEventBase` | Supplies a token and source event. |\n| `DiffTokenEventBaseProps` | Adds diff side data to a token event. |\n| `ObservedAnnotationNodes` | Stores DOM nodes for observed annotations. |\n| `ObservedGridNodes` | Stores DOM nodes for observed grid columns. |\n| `SharedRenderState` | Holds shared token transformer render state. |\n| `StickySpecs` | Describes sticky header position and height. |\n\n## Render results and virtualization\n\n| Export | Purpose |\n| --------------------------- | ------------------------------------------------------- |\n| `RenderFileOptions` | Defines the resolved options for a highlighted file. |\n| `RenderDiffOptions` | Defines the resolved options for a highlighted diff. |\n| `ForceFilePlainTextOptions` | Selects a plain-text file range. |\n| `ForceDiffPlainTextOptions` | Selects a plain-text diff range and hunk state. |\n| `ThemedFileResult` | Holds the highlighted file syntax tree and line count. |\n| `ThemedDiffResult` | Holds highlighted additions and deletions syntax trees. |\n| `RenderDiffFilesResult` | Holds the resolved old and new file inputs. |\n| `RenderFileResult` | Holds file output and the options that produced it. |\n| `RenderDiffResult` | Holds diff output and the options that produced it. |\n| `RenderedFileASTCache` | Stores one cached file syntax tree by theme. |\n| `RenderedDiffASTCache` | Stores one cached diff syntax tree by theme. |\n| `AppliedThemeStyleCache` | Stores applied light and dark theme CSS. |\n| `RenderRange` | Describes a start row, row count, and buffer sizes. |\n| `RenderWindow` | Describes first and last rows in a render window. |\n| `VirtualWindowSpecs` | Describes viewport position, height, and row window. |\n| `VirtualFileMetrics` | Describes estimated header and line heights. |\n\n## Tokenization and diff types\n\n| Export | Purpose |\n| ----------------------------------------------------- | -------------------------------------------------------------------- |\n| `DiffsTheme` | Shared editor colors with optional TextMate and Zed syntax palettes. |\n| `ThemedToken` | One styled token with content, offset, color, and optional styles. |\n| `TokensResult` | Token rows and root colors/styles. |\n| `CodeToTokensOptions`, `CodeToHtmlOptions` | Select a language, themes, and tokenization limits. |\n| `DiffsStreamTokenizer` | Incremental tokenization of appended chunks. |\n| `DiffsEditorTokenizer`, `DiffsEditorTokenizerOptions` | Incremental tokenization of document edits. |\n| `CreatePatchOptionsNonabortable` | Configures the underlying patch algorithm. |\n\nImport TextMate registration and Shiki transformer types from `shiki`. Diffs no\nlonger re-exports Shiki's public API.\n","skills/diffs/references/api-worker.md":"# Worker API\n\nThis reference lists every export from `@pierre/diffs/worker`, every public\n`WorkerPoolManager` member, and both worker script entries.\n\n## Runtime exports\n\n| Export | Kind | Purpose |\n| -------------------------------- | -------- | ----------------------------------------------------- |\n| `WorkerPoolManager` | Class | Runs file and diff highlighting across a worker pool. |\n| `getOrCreateWorkerPoolSingleton` | Function | Gets or creates the module-wide worker pool. |\n| `terminateWorkerPoolSingleton` | Function | Terminates and clears the module-wide worker pool. |\n\n## `WorkerPoolManager` members\n\n| Member | Purpose |\n| -------------------------------------------------------------- | ------------------------------------------------- |\n| `new WorkerPoolManager(options, renderOptions)` | Creates a worker pool. |\n| `initialize(languages?)` | Starts workers and loads languages. |\n| `isInitialized()` | Reports whether initialization finished. |\n| `isWorkingPool()` | Reports whether workers can accept work. |\n| `setRenderOptions(options)` | Updates theme and render settings in each worker. |\n| `getFileRenderOptions()` | Gets active file render options. |\n| `getDiffRenderOptions()` | Gets active diff render options. |\n| `highlightFileAST(instance, file)` | Queues a highlighted file result for an instance. |\n| `highlightDiffAST(instance, diff)` | Queues a highlighted diff result for an instance. |\n| `primeFileHighlightCache(file)` | Preloads one highlighted file result. |\n| `primeDiffHighlightCache(diff)` | Preloads one highlighted diff result. |\n| `getFileResultCache(file)` | Gets one cached file result. |\n| `getDiffResultCache(diff)` | Gets one cached diff result. |\n| `getPlainFileAST(file, start, total, lines?)` | Gets a plain-text file result. |\n| `getPlainDiffAST(diff, start, total, expansions?, threshold?)` | Gets a plain-text diff result. |\n| `inspectCaches()` | Gets both result caches. |\n| `evictFileFromCache(cacheKey)` | Removes one file cache entry. |\n| `evictDiffFromCache(cacheKey)` | Removes one diff cache entry. |\n| `subscribeToThemeChanges(instance)` | Subscribes a render instance to theme changes. |\n| `unsubscribeToThemeChanges(instance)` | Removes a theme subscription. |\n| `subscribeToStatChanges(callback)` | Subscribes to worker statistics. |\n| `cleanUpTasks(instance)` | Removes queued and active tasks for an instance. |\n| `getStats()` | Gets worker and cache statistics. |\n| `terminate()` | Stops workers and clears pool resources. |\n\n## Configuration and state types\n\n| Export | Purpose |\n| ----------------------------------- | ----------------------------------------------------------------- |\n| `SetupWorkerPoolProps` | Combines pool and highlighter options for the singleton. |\n| `WorkerPoolOptions` | Defines the worker factory, pool size, and cache size. |\n| `WorkerInitializationRenderOptions` | Defines initial languages, theme, highlighter, and diff settings. |\n| `WorkerRenderingOptions` | Defines the complete worker render settings. |\n| `WorkerStats` | Describes pool state, work counts, subscribers, and cache sizes. |\n| `WorkerRequestId` | Identifies one worker request. |\n| `ResolvedLanguage` | Holds a resolved language registration. |\n| `FileRendererInstance` | Defines callbacks for a file render consumer. |\n| `DiffRendererInstance` | Defines callbacks for a diff render consumer. |\n\n## Request and response types\n\n| Export | Purpose |\n| ------------------------------- | ------------------------------------------------------- |\n| `WorkerRequest` | Represents any request sent to a worker. |\n| `InitializeWorkerRequest` | Starts a worker with themes, languages, and options. |\n| `SetRenderOptionsWorkerRequest` | Updates render options and themes. |\n| `RenderFileRequest` | Requests one file render. |\n| `RenderDiffRequest` | Requests one diff render. |\n| `SubmitRequest` | Represents a file or diff request before ID assignment. |\n| `WorkerResponse` | Represents any worker response. |\n| `InitializeSuccessResponse` | Confirms worker initialization. |\n| `RegisterThemeSuccessResponse` | Confirms a render-option and theme update. |\n| `RenderSuccessResponse` | Represents a successful file or diff render. |\n| `RenderFileSuccessResponse` | Returns one file render result. |\n| `RenderDiffSuccessResponse` | Returns one diff render result. |\n| `RenderErrorResponse` | Returns a serialized worker error. |\n\n## Task types\n\n| Export | Purpose |\n| ---------------------------- | ------------------------------------------------- |\n| `AllWorkerTasks` | Represents any manager task. |\n| `InitializeWorkerTask` | Tracks one initialization request. |\n| `SetRenderOptionsWorkerTask` | Tracks one render-option update. |\n| `RenderFileTask` | Tracks one file render request and its consumers. |\n| `RenderDiffTask` | Tracks one diff render request and its consumers. |\n| `RenderTaskCallbacks` | Resolves or rejects one render task consumer. |\n\n## Worker script entries\n\n| Import | Purpose |\n| ----------------------------------------- | -------------------------------------------------------------------------------- |\n| `@pierre/diffs/worker/worker.js` | Supplies the module worker that uses package dependencies. |\n| `@pierre/diffs/worker/worker-portable.js` | Supplies a single script with all highlighter backends and dependencies bundled. |\n\nFor static hosting, copy `dist/worker/worker-portable.js` and start it with\n`new Worker(url)`. It also supports module workers and blob URLs, including VS\nCode webviews, without another bundling step. All backends are included in the\ndownload; only the selected backend is initialized. For lazy backend loading,\nuse the regular worker entry with your bundler.\n\nThe pool resolves themes and Shiki grammars on the main thread and sends them to\nthe worker. Their catalogs are excluded from the portable script.\n\nA pool is optional. When one is supplied, highlighting goes through its workers\nfor every backend. Highlights is often fast enough on the main thread to skip\nthe pool.\n","skills/diffs/references/recipe-annotations.md":"# Recipe: add line annotations and selection\n\nPass annotation data and a renderer to the surface:\n\n```tsx\nimport type { DiffLineAnnotation } from '@pierre/diffs/react';\nimport { MultiFileDiff } from '@pierre/diffs/react';\n\nconst annotations: DiffLineAnnotation<{ message: string }>[] = [\n {\n side: 'additions',\n lineNumber: 8,\n metadata: { message: 'Review this line.' },\n },\n];\n\n

{annotation.metadata.message}

}\n options={{\n enableLineSelection: true,\n onLineSelectionEnd(range) {\n saveSelection(range);\n },\n }}\n/>;\n```\n\nUse `LineAnnotation` for a single file. Use `DiffLineAnnotation` for a diff.\nControl the active selection with the `selectedLines` prop.\n","skills/diffs/references/recipe-code-view.md":"# Recipe: build a `CodeView`\n\nUse `CodeView` when one scroll region contains many files, diffs, or both. It\nmanages item virtualization, sticky headers, list-wide selection, and item or\nline scroll targets.\n\n## Contents\n\n- [Select item ownership](#select-item-ownership)\n- [Define items](#define-items)\n- [Use controlled React state](#use-controlled-react-state)\n- [Use imperative ownership](#use-imperative-ownership)\n- [Enable item edit mode](#enable-item-edit-mode)\n\n## Select item ownership\n\n| Host and data flow | Input | Update API |\n| ------------------------------------------- | ----------------- | ------------------------------------ |\n| React owns the complete list | `items` | Publish a new `items` array. |\n| React hosts a large or append-only list | `initialItems` | Use the `CodeViewHandle` methods. |\n| Vanilla JavaScript owns the viewer instance | `setItems(items)` | Use the `CodeView` instance methods. |\n\nKeep one ownership mode for the life of a mounted React viewer. Use controlled\nstate when item data already belongs to React. Use imperative ownership for a\nlarge or streamed list.\n\n## Define items\n\nGive each item a stable and unique `id`. Use a `file` item for `FileContents`.\nUse a `diff` item for `FileDiffMetadata`.\n\nIncrement `version` when an existing item changes its contents, annotations,\ncollapsed state, or edit state. `CodeView` uses the ID and version to select the\nitem that it must update.\n\n## Use controlled React state\n\n```tsx\nimport {\n parseDiffFromFile,\n type CodeViewItem,\n type CodeViewLineSelection,\n} from '@pierre/diffs';\nimport { CodeView, type CodeViewHandle } from '@pierre/diffs/react';\nimport { useRef, useState } from 'react';\n\nconst oldFile = {\n name: 'src/value.ts',\n contents: 'export const value = 1;',\n};\nconst newFile = {\n name: 'src/value.ts',\n contents: 'export const value = 2;',\n};\nconst codeViewStyle = { height: 600, overflow: 'auto' } as const;\nconst codeViewOptions = {\n theme: { light: 'pierre-light', dark: 'pierre-dark' },\n stickyHeaders: true,\n enableLineSelection: true,\n layout: { paddingTop: 16, paddingBottom: 16, gap: 12 },\n} as const;\n\nexport function ReviewSurface() {\n const viewerRef = useRef | null>(null);\n const [selection, setSelection] = useState(\n null\n );\n const [items, setItems] = useState(() => [\n {\n id: 'diff:src/value.ts',\n type: 'diff',\n fileDiff: parseDiffFromFile(oldFile, newFile),\n version: 0,\n },\n {\n id: 'file:README.md',\n type: 'file',\n file: { name: 'README.md', contents: '# Review notes' },\n version: 0,\n },\n ]);\n\n function toggleDiff() {\n setItems((current) =>\n current.map((item) =>\n item.id === 'diff:src/value.ts'\n ? {\n ...item,\n collapsed: !item.collapsed,\n version: (item.version ?? 0) + 1,\n }\n : item\n )\n );\n }\n\n return (\n <>\n \n \n viewerRef.current?.scrollTo({\n type: 'line',\n id: 'diff:src/value.ts',\n lineNumber: 1,\n side: 'additions',\n align: 'center',\n })\n }\n >\n Jump to change\n \n \n \n );\n}\n```\n\n## Use imperative ownership\n\nIn React, pass `initialItems` and keep `items` unset. Use the component ref to\ncall `addItems`, `getItem`, `updateItem`, `updateItemId`, or `scrollTo`.\n\nIn vanilla JavaScript, configure and populate the instance directly:\n\n```ts\nimport { CodeView, parseDiffFromFile } from '@pierre/diffs';\n\nconst root = document.querySelector('#review');\nif (root == null) throw new Error('Missing review host');\n\nconst oldFile = {\n name: 'src/value.ts',\n contents: 'export const value = 1;',\n};\nconst newFile = {\n name: 'src/value.ts',\n contents: 'export const value = 2;',\n};\n\nconst viewer = new CodeView({\n theme: { light: 'pierre-light', dark: 'pierre-dark' },\n stickyHeaders: true,\n enableLineSelection: true,\n onSelectedLinesChange(selection) {\n console.log('selected lines', selection);\n },\n});\n\nroot.style.height = '600px';\nroot.style.overflow = 'auto';\nviewer.setup(root);\nviewer.setItems([\n {\n id: 'diff:src/value.ts',\n type: 'diff',\n fileDiff: parseDiffFromFile(oldFile, newFile),\n version: 0,\n },\n]);\n\nviewer.addItems([\n {\n id: 'file:README.md',\n type: 'file',\n file: { name: 'README.md', contents: '# Review notes' },\n version: 0,\n },\n]);\nviewer.scrollTo({\n type: 'item',\n id: 'diff:src/value.ts',\n align: 'start',\n});\n\nconst item = viewer.getItem('diff:src/value.ts');\nif (item != null) {\n viewer.updateItem({\n ...item,\n collapsed: true,\n version: (item.version ?? 0) + 1,\n });\n}\n\nexport function removeReviewSurface() {\n viewer.cleanUp();\n}\n```\n\n## Enable item edit mode\n\nIn React, wrap `CodeView` in `EditProvider`. In vanilla JavaScript, pass\n`createEditor(editorType, options, editStateKey)` in `CodeViewOptions` and\nforward all three arguments to `new Editor`. Set `edit: true` on each editable\nitem and increment its version. The factory receives `'file'` or `'file-diff'`\nas its first argument so it can construct an editor of the requested type.\n\n`onItemEditChange(event, item)` reports live contents and annotation changes.\nRead the current document from `event.file`, the complete annotation collection\nfrom `event.lineAnnotations`. Treat it as a notification and do not feed the\nchanges back into the viewer.\n\n`onItemEditComplete(event, item, nextItem)` must return `'accept'` or `'reject'`\nwhenever a session ends, including when its final text is unchanged. `CodeView`\nbuilds `nextItem` with the completed contents and annotations, `edit: false`,\nand an incremented `version`. If you use keyed render caching, assign a fresh\n`cacheKey` to `event.file` or `event.fileDiff` before accepting. Return\n`'accept'` to install `nextItem` while the item remains present, or `'reject'`\nto restore the original item while it remains present. During removal or viewer\nteardown, neither decision reinserts the item. A missing callback rejects. When\nReact controls `items`, put `nextItem` into controlled state only when the item\nshould remain.\n\nUse `getEditStateKey(item)` to opt into retaining the draft, undo/redo history,\nselections, and editor-owned view state across editor instances. The returned\n`editStateKey` is passed to the editor factory. `getEditor(id)` returns the\ncurrent `Editor` instance.\n\nRead [Edit with React](recipe-edit-react.md) or\n[Edit with vanilla JavaScript](recipe-edit-vanilla.md) for the complete editor\nlifecycle.\n","skills/diffs/references/recipe-custom-highlighting.md":"# Recipe: register custom highlighting\n\nRegister themes before rendering. For a Zed-compatible theme with Highlights:\n\n```tsx\nimport { registerCustomTheme } from '@pierre/diffs';\nimport { FileDiff } from '@pierre/diffs/react';\n\nregisterCustomTheme('app-dark', () => import('./my-zed-theme.json'), 'zed');\n\n;\n```\n\nFor TextMate themes and custom grammars, use Shiki:\n\n```ts\nimport { registerCustomLanguage, registerCustomTheme } from '@pierre/diffs';\n\nregisterCustomLanguage(\n 'my-language',\n () => import('./my-language.tmLanguage.json'),\n ['myext']\n);\nregisterCustomTheme('my-theme', () => import('./my-textmate-theme.json'));\n```\n\nSet `file.lang` and `options.theme` to the registered names. Custom languages\napply to Shiki; Highlights bundles its lexers and ignores custom grammars.\n\nFor a CSS palette that works across backends:\n\n```ts\nimport { registerCustomCSSVariableTheme } from '@pierre/diffs';\n\nregisterCustomCSSVariableTheme('app-palette', {\n foreground: '#eeeeee',\n background: '#101010',\n 'token-keyword': '#c084fc',\n 'token-string-expression': '#86efac',\n});\n```\n\nThis registers a shared Diffs theme using `--diffs-*` variables. See\n[Highlighting API](api-highlighting.md#themes) for loader formats, name\nmatching, and CSS palette options.\n","skills/diffs/references/recipe-edit-react.md":"# Recipe: edit with React\n\nMount one `EditProvider` above the editable surfaces. Its factory receives the\neditor type, the surface's creation-time `editorOptions`, and an optional\n`editStateKey`. Each active surface or `CodeView` item owns its editor.\n\nPass `editStateKey` to opt into bounded in-memory retention of the draft,\nundo/redo history, selections, horizontal scroll, eligible vertical scroll, and\ndiff resume metadata across editor instances. Choose this key explicitly; it is\na stable application identity for the document. The same active key cannot be\nshared by two editors of the same type.\n\n## Contents\n\n- [Edit a standalone file or diff](#edit-a-standalone-file-or-diff)\n- [Keep annotations synchronized](#keep-annotations-synchronized)\n- [Edit CodeView items](#edit-codeview-items)\n\n## Edit a standalone file or diff\n\nSet `edit` on `File`, `FileDiff`, `MultiFileDiff`, or `PatchDiff`. Pass editor\ncreation options through `editorOptions` and optional retention through\n`editStateKey`.\n\n```tsx\nimport type { FileContents, FileDiffOptions } from '@pierre/diffs';\nimport {\n Editor,\n type EditorChangeEvent,\n type EditorFactory,\n type EditorOptions,\n type FileDiffEditCompleteEvent,\n} from '@pierre/diffs/edit';\nimport { EditProvider, MultiFileDiff, Virtualizer } from '@pierre/diffs/react';\nimport { useMemo, useRef, useState } from 'react';\n\nconst oldFile: FileContents = {\n name: 'src/value.ts',\n contents: 'export const value = 1;',\n};\nconst initialNewFile: FileContents = {\n name: 'src/value.ts',\n contents: 'export const value = 2;',\n};\nconst diffOptions: FileDiffOptions = {\n theme: { light: 'pierre-light', dark: 'pierre-dark' },\n diffStyle: 'split',\n};\n\nconst createEditor: EditorFactory = (\n editorType,\n options,\n editStateKey?: string\n) => new Editor(editorType, options, editStateKey);\n\nexport function EditableDiff() {\n const [edit, setEdit] = useState(false);\n const [newFile, setNewFile] = useState(initialNewFile);\n const editorRef = useRef | null>(null);\n const editorOptions = useMemo<\n EditorOptions<'file-diff', undefined, undefined>\n >(\n () => ({\n onAttach(editor) {\n editorRef.current = editor;\n },\n }),\n []\n );\n\n function toggleEdit() {\n setEdit((value) => !value);\n }\n\n function handleEditChange(\n event: EditorChangeEvent<'file-diff', undefined, undefined>\n ) {\n saveDraft(event.file);\n }\n\n function handleEditComplete(\n event: FileDiffEditCompleteEvent\n ) {\n if (event.newFile != null) {\n setNewFile(event.newFile);\n }\n return 'accept' as const;\n }\n\n return (\n \n \n editorRef.current?.undo()}\n >\n Undo\n \n \n \n \n \n );\n}\n```\n\nMount the provider near the application root when many surfaces use edit mode.\nAlways forward all three factory arguments. Use `onAttach` when controls need\n`undo`, `redo`, `applyEdits`, selections, markers, focus, or other editor APIs.\n`EditStateManager` only manages sessions retained with `editStateKey`; unkeyed\nsessions require no manager cleanup. For keyed sessions, use\n`EditStateManager.clear(type, key)` after a session becomes inactive when its\nretained draft should be discarded. `clearAll()` clears inactive state in both\nnamespaces, and `setCapacity(capacity)` changes each namespace's default limit\nof 100 entries. Active state is never mutated by manager clearing.\n\n## Keep annotations synchronized\n\nEdit mode owns annotation positions during an active session. Change events\nexpose the remapped collection for observation, but do not feed it back into the\nsurface. On acceptance, store the completion event's final annotations beside\nthe accepted file or diff. Use `isFileAnnotationCollection` or\n`isDiffAnnotationCollection` when the surface type is not already known, and key\nannotation UI state by a stable metadata ID instead of a line number.\n\n## Edit `CodeView` items\n\nWrap `CodeView` in the same `EditProvider`. Set `edit: true` on an item and\nincrement its `version`. Pass shared creation options through the `CodeView`\n`editorOptions` prop. Use `getEditStateKey(item)` for opt-in draft, history,\nselection, and view-state retention.\n\nUse `onItemEditChange` for live contents and annotation changes. Use\n`onItemEditComplete` to accept or reject every ended session, including when its\nfinal text is unchanged. If you use keyed render caching, assign a fresh\n`cacheKey` to the event's file or diff. Put the supplied `nextItem` into\ncontrolled state only while the item should remain, then return `'accept'`;\nacceptance during removal or teardown does not reinsert it. `CodeView` builds\n`nextItem` with `edit: false` and an incremented `version`.\n\n`CodeViewHandle.getEditor(id)` returns the current `Editor` instance. The item\neditor keeps its active document and history when virtualization or collapse\nremoves the item from the rendered window. `getEditStateKey` extends that\nretention to later editor instances after the edit session ends.\n\nWhen a worker pool highlights an editable surface, set\n`useTokenTransformer: true` in the worker `highlighterOptions`.\n","skills/diffs/references/recipe-edit-vanilla.md":"# Recipe: edit with vanilla JavaScript\n\nRender a standalone surface first. Then attach one `Editor` to it. Use one\neditor for each surface that can be edited at the same time.\n\n## Contents\n\n- [Edit a standalone diff](#edit-a-standalone-diff)\n- [Edit CodeView items](#edit-codeview-items)\n\n## Edit a standalone diff\n\n```ts\nimport {\n FileDiff,\n type DiffLineAnnotation,\n type FileContents,\n} from '@pierre/diffs';\nimport { Editor } from '@pierre/diffs/edit';\n\ninterface ThreadMetadata {\n id: string;\n}\n\nconst hostElement = document.querySelector('#diff');\nif (hostElement == null) throw new Error('Missing diff host');\nconst host: HTMLElement = hostElement;\n\nconst oldFile: FileContents = {\n name: 'src/value.ts',\n contents: 'export const value = 1;',\n};\nlet newFile: FileContents = {\n name: 'src/value.ts',\n contents: 'export const value = 2;',\n};\nlet annotations: DiffLineAnnotation[] = [\n {\n side: 'additions',\n lineNumber: 1,\n metadata: { id: 'value-review' },\n },\n];\nconst view = new FileDiff({\n theme: { light: 'pierre-light', dark: 'pierre-dark' },\n onEditChange(event) {\n saveDraft(event.file);\n },\n onEditComplete(event) {\n if (event.newFile != null) {\n newFile = event.newFile;\n }\n if (event.lineAnnotations != null) {\n annotations = event.lineAnnotations;\n }\n return 'accept';\n },\n renderAnnotation(annotation) {\n const element = document.createElement('p');\n element.textContent = 'Thread ' + annotation.metadata.id;\n return element;\n },\n});\n\nfunction render() {\n view.render({\n fileContainer: host,\n oldFile,\n newFile,\n lineAnnotations: annotations,\n });\n}\n\nrender();\n\nconst editor = new Editor<'file-diff', ThreadMetadata>(\n 'file-diff',\n {},\n 'src/value.ts:draft'\n);\nlet finishEditing: (() => void) | undefined = editor.edit(view);\n\nexport function stopEditing() {\n const finish = finishEditing;\n finishEditing = undefined;\n finish?.();\n}\n\nexport function removeSurface() {\n stopEditing();\n view.cleanUp();\n}\n```\n\n`onEditChange` receives one `EditorChangeEvent`. Observe its remapped\n`lineAnnotations`, but do not feed them back into the surface during the active\nsession. Store the final collection from `onEditComplete` alongside the accepted\nfile or diff. Use stable metadata IDs for application state that belongs to an\nannotation.\n\nPass a third `editStateKey` argument to `new Editor` when a later editor\ninstance should resume/save the in-memory draft, undo/redo history, selections,\nand editor-owned view state.\n\nUse `VirtualizedFile` or `VirtualizedFileDiff` with a `Virtualizer` for a large\nstandalone surface. Load `@pierre/diffs/edit` with `import()` when edit mode is\noptional and the initial bundle must omit the editor.\n\n## Edit `CodeView` items\n\nPass a factory through `CodeViewOptions.createEditor`:\n\n```ts\nimport { CodeView } from '@pierre/diffs';\nimport { Editor } from '@pierre/diffs/edit';\n\nexport function mountEditableCodeView(root: HTMLElement) {\n const viewer = new CodeView({\n getEditStateKey(item) {\n return 'draft:' + item.id;\n },\n createEditor(editorType, options, editStateKey) {\n return new Editor(editorType, options, editStateKey);\n },\n onItemEditChange(event, item) {\n saveItemDraft(item.id, event.file, event.lineAnnotations);\n },\n onItemEditComplete(event, item, nextItem) {\n if (item.type !== 'file' || !('file' in event)) return 'reject';\n\n // Re-key only if this item participates in keyed render caching.\n event.file.cacheKey = item.id + ':v' + nextItem.version;\n return 'accept';\n },\n });\n\n viewer.setup(root);\n viewer.setItems([\n {\n id: 'file:src/value.ts',\n type: 'file',\n file: {\n name: 'src/value.ts',\n contents: 'export const value = 1;',\n },\n edit: true,\n version: 0,\n },\n ]);\n\n return viewer;\n}\n```\n\nSet `edit: true` on an item and increment its `version`. `onItemEditChange`\nreceives `(event, item)`; use `event.file` and `event.lineAnnotations` without\nfeeding the change back into the viewer. Completion receives\n`(event, item, nextItem)` whenever a session ends, including when its final text\nis unchanged. `CodeView` builds `nextItem` with the final contents and\nannotations, `edit: false`, and an incremented `version`. If you use keyed\nrender caching, assign a fresh `cacheKey` to `event.file` or `event.fileDiff`.\nReturn `'accept'` to install `nextItem` while the item remains present or\n`'reject'` to restore the original item while it remains present. During removal\nor viewer teardown, neither decision reinserts the item. A missing completion\ncallback rejects. A controlled React owner should put `nextItem` into its\n`items` state only when the item should remain.\n\n`getEditStateKey(item)` opts an item into draft, undo/redo, selection, and\neditor-owned view-state retention across editor instances. Forward the resulting\nthird factory argument to `new Editor`. `CodeView` creates and removes the item\neditors.\n\n`viewer.getEditor(id)` returns the current `Editor` instance. Call\n`viewer.cleanUp()` when the host removes the viewer.\n\nWhen a worker pool highlights an editable surface, set\n`useTokenTransformer: true` in the worker `highlighterOptions`.\n","skills/diffs/references/recipe-react.md":"# Recipe: render with React\n\n## Select a surface\n\n| Input or layout | Component |\n| ------------------------------------------- | ---------------- |\n| One `FileContents` object | `File` |\n| Old and new `FileContents` objects | `MultiFileDiff` |\n| Existing `FileDiffMetadata` | `FileDiff` |\n| One unified patch string | `PatchDiff` |\n| One file with merge conflicts | `UnresolvedFile` |\n| One scroll region with many files and diffs | `CodeView` |\n\nUse `MultiFileDiff` when the app has old and new file contents:\n\n```tsx\nimport { MultiFileDiff } from '@pierre/diffs/react';\n\n;\n```\n\nPass source data, annotations, and slot renderers as component props. Pass\ndisplay, theme, interaction, and highlighting settings through `options`.\n\nKeep file objects and option objects stable when their values do not change.\nWrap a large standalone surface in `Virtualizer`. Use `CodeView` when one scroll\nregion contains a list of files or diffs.\n\nUse the matching preload function from `@pierre/diffs/ssr` when the server must\nrender the initial highlighted markup.\n","skills/diffs/references/recipe-ssr.md":"# Recipe: preload a diff on the server\n\nCreate props on the server and pass the result to the matching React component:\n\n```tsx\nimport { preloadMultiFileDiff } from '@pierre/diffs/ssr';\nimport { MultiFileDiff } from '@pierre/diffs/react';\n\nconst preloaded = await preloadMultiFileDiff({\n oldFile: { name: 'src/value.ts', contents: oldSource },\n newFile: { name: 'src/value.ts', contents: newSource },\n options: { theme: 'pierre-dark', diffStyle: 'split' },\n});\n\n;\n```\n\nSelect the preload function that matches the client component. Use\n`preloadDiffHTML` or `preloadUnresolvedFileHTML` when the host needs an HTML\nstring only.\n","skills/diffs/references/recipe-vanilla.md":"# Recipe: render with vanilla JavaScript\n\n## Select a surface\n\n| Input or layout | Class |\n| ------------------------------------------- | --------------------- |\n| One `FileContents` object | `File` |\n| Existing or parsed `FileDiffMetadata` | `FileDiff` |\n| One file with merge conflicts | `UnresolvedFile` |\n| One large file | `VirtualizedFile` |\n| One large diff | `VirtualizedFileDiff` |\n| One scroll region with many files and diffs | `CodeView` |\n\nParse the files, create the view, and render it into a host:\n\n```ts\nimport { FileDiff, parseDiffFromFile } from '@pierre/diffs';\n\nconst host = document.querySelector('#diff');\nif (host == null) throw new Error('Missing diff host');\n\nconst fileDiff = parseDiffFromFile(\n { name: 'src/value.ts', contents: oldSource },\n { name: 'src/value.ts', contents: newSource }\n);\n\nconst view = new FileDiff({\n diffStyle: 'split',\n theme: 'pierre-dark',\n});\n\nview.render({ fileContainer: host, fileDiff });\n```\n\nKeep the class instance while the host remains mounted. Call `render` again when\nthe source data changes. Call `setOptions`, `setThemeType`,\n`setLineAnnotations`, or `setSelectedLines` for targeted updates.\n\nUse a `Virtualizer` with `VirtualizedFile` or `VirtualizedFileDiff` for one\nlarge surface. Use `CodeView` for a list that shares one scroll region. Call\n`cleanUp()` when the host removes the surface.\n","skills/diffs/references/recipe-workers.md":"# Recipe: use a worker pool\n\nWrap React diff surfaces in one provider:\n\n```tsx\nimport { WorkerPoolContextProvider } from '@pierre/diffs/react';\n\n\n new Worker(new URL('@pierre/diffs/worker/worker.js', import.meta.url), {\n type: 'module',\n }),\n }}\n highlighterOptions={{\n langs: ['typescript', 'tsx'],\n theme: { light: 'pierre-light', dark: 'pierre-dark' },\n }}\n>\n {children}\n;\n```\n\nFor vanilla JavaScript, call `getOrCreateWorkerPoolSingleton` and pass the\nresult as the second constructor argument to a render class. Call\n`terminateWorkerPoolSingleton()` when the application tears down the shared\npool.\n","skills/highlights/SKILL.md":"---\nname: highlights\ndescription:\n Use when an app uses @pierre/highlights to generate syntax-highlighted HTML or\n tokens, stream code, incrementally tokenize edits, or apply Zed-compatible\n themes and CSS variables.\n---\n\n# `@pierre/highlights`\n\nUse `@pierre/highlights` for standalone syntax highlighting with built-in\nWebAssembly lexers. Choose HTML for a complete code block, tokens for a custom\nrenderer, `StreamTokenizer` for append-only input, or `LiveTokenizer` for an\neditable document.\n\n## Install\n\n```bash\npnpm add @pierre/highlights\n```\n\nImport from `@pierre/highlights`. Conditional exports initialize WebAssembly\nautomatically for Node.js, browsers, and Cloudflare Workers. Highlighting is\nsynchronous after import; ordinary usage needs no `init()` or language\nregistration.\n\n## Select a reference\n\n| Task | Reference |\n| -------------------------------------------------------------------------- | ----------------------------------------- |\n| Generate HTML or tokens, validate a language, or manage a Wasm module | [Rendering](references/rendering.md) |\n| Load or customize themes, switch CSS variables, or render multiple schemes | [Themes](references/themes.md) |\n| Tokenize streamed strings or bytes | [Streaming](references/streaming.md) |\n| Apply edits, prioritize a viewport, or read packed token records | [Incremental editing](references/live.md) |\n\nFor file, diff, or editor components, read the [diffs skill](../diffs/SKILL.md).\n","skills/highlights/references/live.md":"# Incremental editing\n\n`LiveTokenizer` owns a document and an isolated WebAssembly instance. It\nre-tokenizes changed lines and following lines until the lexer state converges\nwith the retained state. Constructor options extend the\n[tokenization options](rendering.md#options-and-languages) with `code` (default\nempty), `renderRange`, and `onDeferTokenize`.\n\n## Apply edits\n\n```ts\nimport { LiveTokenizer } from '@pierre/highlights';\nimport { pierreDark } from '@pierre/highlights/themes';\n\nconst live = new LiveTokenizer({\n code: 'const answer = 41;\\nconsole.log(answer);',\n lang: 'ts',\n theme: pierreDark,\n});\n\ntry {\n const update = live.applyEdits([\n {\n range: {\n start: { line: 0, character: 15 },\n end: { line: 0, character: 17 },\n },\n newText: '42',\n },\n ]);\n\n console.log(live.getLineText(0)); // const answer = 42;\n for (const change of update.lineChanges) {\n for (let line = change.newStartLine; line < change.newEndLine; line++) {\n console.log(line, live.getLineTokens(line));\n }\n }\n} finally {\n live.dispose();\n}\n```\n\nEvery edit range uses zero-based lines and UTF-16 character positions in the\ndocument before the batch. The end position is exclusive. Overlapping ranges are\nrejected before mutation. `reset(code, options?)` replaces the whole text while\nretaining language and theme options; recreate the tokenizer to change those\noptions.\n\nWithout `renderRange`, updates finish synchronously and `update.lines` is empty.\nUse `lineChanges` and `getLineTokens()` to refresh a renderer. Each\n`LiveLineChange` maps `[oldStartLine, oldEndLine)` to\n`[newStartLine, newEndLine)`; also remove deleted rows when reconciling a view.\n`LiveTokenizerUpdate` includes `revision`, `previousLineCount`, and `lineCount`.\n\n`getLineTokens(line)` returns `{ tokens, bracketIgnoredRanges }`. Its token\noffsets are relative to that line. `bracketIgnoredRanges` contains end-exclusive\nUTF-16 column pairs for strings, comments, and regexes that bracket matching\nshould skip.\n\n## Prioritize a viewport\n\n`renderRange: [startLine, endLine]` uses post-edit line numbers and excludes\n`endLine`. Pass it on each update that should prioritize a viewport. Dirty lines\nbefore the viewport must also be processed to establish lexer state; the\nremaining work runs in background slices.\n\n```ts\nimport { LiveTokenizer } from '@pierre/highlights';\nimport { pierreDark } from '@pierre/highlights/themes';\n\nconst live = new LiveTokenizer({\n code: 'const answer = 41;\\nconsole.log(answer);',\n lang: 'ts',\n theme: pierreDark,\n renderRange: [0, 1],\n onDeferTokenize(lines) {\n // This callback can run before the constructor returns.\n for (const [line, tokens] of lines) console.log(line, tokens);\n },\n});\n\ntry {\n console.log(live.getLineTokens(0)); // Read the initial viewport after construction.\n const update = live.applyEdits(\n [\n {\n range: {\n start: { line: 0, character: 15 },\n end: { line: 0, character: 17 },\n },\n newText: '42',\n },\n ],\n { renderRange: [0, 1] }\n );\n for (const [line, tokens] of update.lines) console.log(line, tokens);\n\n live.flush(); // Finish pending work before reading the complete document's tokens.\n} finally {\n live.dispose();\n}\n```\n\n`update.lines` contains re-tokenized lines inside the range, not the entire\nviewport. Finished lines outside it arrive through `onDeferTokenize`, which can\nrun synchronously during construction or an update. Keep the callback\nindependent of the variable receiving the new instance. Schedule further edits\nafter the current update; calling `applyEdits()` or `reset()` inside its\nsynchronous callback throws.\n\nBoth maps contain `HighlightedToken[]`: tuples of\n`[character, foregroundColor, text]` using the first resolved theme. Read\n`getLineTokens()` when font styles or multi-theme `htmlStyle` maps are needed.\nWhile `pendingTokenization` is true, unreached lines can retain old tokens and\nnew lines can have foreground-only tokens. Call `flush()` before reads that\nrequire fully current tokens.\n\n## Document and lifecycle API\n\n| Member | Purpose |\n| ---------------------------------------------- | ---------------------------------------------------------------------------- |\n| `revision`, `lineCount`, `pendingTokenization` | Read document revision, line count, and pending work |\n| `applyEdits(edits, options?)` | Apply a batch and return `LiveTokenizerUpdate` |\n| `reset(code, options?)` | Replace text and return `LiveTokenizerUpdate` |\n| `getLineLength(line)`, `getLineText(line)` | Read UTF-16 length or text excluding the terminator |\n| `getText()` | Read all text, preserving LF, CRLF, and lone CR |\n| `getLineTokens(line)` | Read themed tokens and bracket-ignored ranges |\n| `getLineRecords(line)` | Read packed raw token records |\n| `flush(endLine?)` | Finish pending work before an exclusive line bound, or all work when omitted |\n| `pause()`, `resume()` | Suspend or resume background tokenization |\n| `dispose()` | Release the instance and cancel deferred work; safe to repeat |\n\n`flush()`, `reset()`, and `applyEdits()` (even a no-op batch) resume paused\nwork. After disposal, other methods and state getters throw. Keep one tokenizer\nfor the document's lifetime and dispose it when the editor unmounts or closes.\n\n## Packed records\n\n`getLineRecords()` returns `LiveTokenRecords` with `revision`, `format`, and\n`data: Uint32Array`. Starts are implicit: zero for the first token, then the\nprevious token's end. End positions are UTF-16 columns within the line.\n\n| Format | Encoding |\n| ---------- | -------------------------------------------------------------------- |\n| `packed24` | One word per token: `tokenId = word >>> 24`, `end = word & 0xffffff` |\n| `wide32` | Pairs of `[endUtf16, tokenId]` for lines exceeding the 24-bit range |\n\nImport `tokenNames` from `@pierre/highlights` to map IDs to syntax scope names.\nViews are invalidated by successful edits, resets, deferred tokenization slices,\nand disposal. Copy `records.data.slice()` before retaining data across those\noperations. Deferred work can invalidate data without changing the document\nrevision.\n\nThe root entry exports `HighlightedToken`, `LiveLineChange`, `LivePosition`,\n`LiveTextEdit`, `LiveTokenizerOptions`, `LiveTokenizerUpdate`,\n`LiveTokenRecords`, and `LiveUpdateOptions`. Use `LivePosition` and\n`LiveTextEdit` for the public position and edit types.\n","skills/highlights/references/rendering.md":"# Rendering\n\n## HTML\n\n```ts\nimport { codeToHtml } from '@pierre/highlights';\nimport { pierreDark } from '@pierre/highlights/themes';\n\nconst html = new TextDecoder().decode(\n codeToHtml('const answer = 42;', { lang: 'ts', theme: pierreDark })\n);\n```\n\n`codeToHtml()` returns UTF-8 bytes for a\n`
…
` fragment. Source text is\nHTML-escaped and theme styles are applied inline. Decode the bytes immediately,\nor call `.slice()` before retaining them across another highlighting or\ntokenization call on the same highlighter. The top-level `codeToHtml()` and\n`codeToTokens()` share one instance.\n\n## Tokens\n\n```ts\nimport { codeToTokens } from '@pierre/highlights';\nimport { pierreDark } from '@pierre/highlights/themes';\n\nconst result = codeToTokens('const answer = 42;\\n', {\n lang: 'ts',\n theme: pierreDark,\n});\n\nconsole.log(result.tokens[0]); // ThemedToken[] for the first line\nconsole.log(result.fg, result.bg); // Root foreground and background colors\n```\n\n`TokensResult.tokens` contains one `ThemedToken[]` per line. Line terminators\nare excluded from content; a trailing line break adds an empty final line.\nOffsets count UTF-16 code units from the start of the complete input.\n\n| Token field | Meaning |\n| ---------------------- | ----------------------------------------------------------------------------- |\n| `content`, `offset` | Text and its absolute UTF-16 start index |\n| `color`, `fontStyle` | Single-theme color and Shiki-style font flags |\n| `htmlStyle` | Multi-theme styles, including custom properties; apply the whole map |\n| `type` | `1` comment, `2` string, `3` regex, otherwise `0` or omitted |\n| `bgColor`, `htmlAttrs` | Optional background and span attributes for renderer/transformer integrations |\n\nHighlights emits italic (`1`) and bold (`2`) font flags. The type also supports\nunderline (`4`) and strikethrough (`8`) supplied by transformers. Use text nodes\nor escape `content` in a custom HTML renderer. Apply root colors as well as\ntoken styles. Token objects are Shiki-compatible; lexer boundaries and syntax\nclassifications can differ.\n\nWith multiple themes, `fg` and `bg` can contain CSS declaration lists, and\n`defaultColor: false` supplies `rootStyle`. See [Themes](themes.md) for\nrendering those styles. Equal runs can share an `htmlStyle` object; replace that\nobject when customizing one token.\n\n## Options and languages\n\nBoth functions accept `string`, `Uint8Array`, or `ArrayBuffer` input; bytes are\nUTF-8. Supply `lang` and exactly one of `theme` or `themes`.\n\n| Option | Meaning |\n| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- |\n| `lang` | Built-in language name or alias, typed as `Lang` |\n| `theme` | One Zed `Theme` or `ThemeFamily` object |\n| `themes` | Non-empty map of named theme objects; see [Themes](themes.md) |\n| `cssVariablePrefix` | Prefix for CSS-variable colors and theme properties; default `--hls-` |\n| `defaultColor` | With `themes`, inline theme key (default `light`), `false`, or `'light-dark()'` |\n| `tokenizeMaxLineLength` | Tokenization only: lines at or above this UTF-16 length become one token without syntax styling; `0` or omission disables it |\n\nThe line-length limit reduces token objects, while the lexer still processes the\nline to preserve subsequent state. It also applies to streaming and live\ntokenization, but is not an HTML option.\n\nLanguage names and aliases are case-insensitive. Unknown names throw\n`RangeError`. Highlights performs no automatic language detection or filename\nresolution. Validate external labels and choose an explicit fallback:\n\n```ts\nimport { isSupportedLanguage } from '@pierre/highlights';\n\nconst requestedLanguage: string = 'typescript';\nconst lang = isSupportedLanguage(requestedLanguage)\n ? requestedLanguage\n : 'plain';\n```\n\n`isSupportedLanguage()` narrows a string to `Lang`. Plain text aliases include\n`plain`, `text`, `plaintext`, and `txt`. Lexers are built in; custom TextMate\ngrammar registration belongs to the Shiki APIs in `@pierre/diffs`.\n\n## Runtime and types\n\n`createHighlighter()` returns an isolated `Highlighter` using the initialized\nmodule. Embedders can pass their own compiled `WebAssembly.Module` to\n`createHighlighter(module)` or replace the shared highlighter with\n`init(module)`. Both functions are synchronous. `Highlighter` exposes\n`codeToHtml()` and `codeToTokens()` with the signatures above. Import the normal\npackage entry for automatic initialization.\n\nCore public types are `Highlighter`, `Lang`, `CodeToHtmlBaseOptions`,\n`CodeToHtmlOptions`, `CodeToTokensBaseOptions`, `CodeToTokensOptions`,\n`ThemeOptions`, `ThemedToken`, and `TokensResult`. Theme types are covered in\n[Themes](themes.md); live types and `tokenNames` in\n[Incremental editing](live.md).\n","skills/highlights/references/streaming.md":"# Streaming\n\n`StreamTokenizer` extends `TransformStream`. It takes\nthe [tokenization options](rendering.md#options-and-languages) and owns an\nisolated WebAssembly instance. Use it for append-only input; use\n[LiveTokenizer](live.md) when previously received text can change.\n\n## Pipe a readable stream\n\nPass a UTF-8 byte stream through the tokenizer with `pipeThrough()`. It decodes\nbytes internally, including characters split across chunks. Given an existing\n`ReadableStream` named `responseBody`:\n\n```ts\nimport { StreamTokenizer } from '@pierre/highlights';\nimport { pierreDark } from '@pierre/highlights/themes';\n\nconst lines = responseBody.pipeThrough(\n new StreamTokenizer({ lang: 'ts', theme: pierreDark })\n);\n\nfor await (const tokens of lines) {\n console.log(tokens); // One ThemedToken[] per line\n}\n```\n\nClosing the writable side emits the remaining lines and releases the instance.\nCancellation or abort discards buffered input and releases it. Let the stream\npipeline manage completion; use the synchronous methods below when manually\nfeeding strings or UTF-8 bytes.\n\n## Push chunks synchronously\n\n```ts\nimport { StreamTokenizer } from '@pierre/highlights';\nimport { pierreDark } from '@pierre/highlights/themes';\n\nconst stream = new StreamTokenizer({ lang: 'ts', theme: pierreDark });\n\ntry {\n console.log(stream.pushCode('const answer =')); // []: incomplete line\n const bytes = new TextEncoder().encode(' 42;\\nconsole.log(answer);');\n console.log(stream.pushCode(bytes)); // First line\n console.log(stream.end()); // Remaining line; also disposes the instance\n} finally {\n stream.dispose();\n}\n```\n\n| Method | Behavior |\n| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |\n| `pushCode(chunk: string \\| Uint8Array)` | Accepts text or UTF-8 bytes; returns `ThemedToken[][]` for completed lines and buffers the unfinished line |\n| `end()` | Finishes decoding and returns remaining lines, including an empty final line after a trailing terminator, then disposes |\n| `dispose()` | Discards buffered input and releases the instance; safe to repeat |\n\nChunks can produce zero or more lines. Lines are emitted when `\\n` arrives,\nincluding in CRLF input, or at `end()`. Lexer state is retained across chunks.\nToken offsets are UTF-16 indices from the start of the complete stream. Apply\nthe same token styles described in [Rendering](rendering.md#tokens).\n\nCall `end()` once when input finishes. Calling `pushCode()` or `end()` after\ndisposal throws. Keep `dispose()` in cleanup paths for cancellation and errors.\n\nUTF-8 characters can span consecutive byte chunks. Mixing strings and bytes\npreserves chunk order: a nonempty string flushes incomplete UTF-8 as a\nreplacement character before appending the string. Empty chunks leave buffered\ninput intact.\n","skills/highlights/references/themes.md":"# Themes\n\nHighlights takes Zed-compatible theme objects. Load them from\n`@pierre/highlights/themes`; `@pierre/theme` supplies Shiki and VS Code objects\nwith a different shape.\n\n## Load a theme\n\n```ts\nimport { pierreDark } from '@pierre/highlights/themes';\nimport vitesseDark from '@pierre/highlights/themes/vitesse-dark';\nimport { themes } from '@pierre/highlights/themes/loader';\n\nconst { default: lazyTheme } = await themes['pierre-dark']();\n```\n\n| Entry | Exports |\n| ---------------------------------- | -------------------------------------------------------- |\n| `@pierre/highlights/themes` | Camel-case named themes, `cssVariables`, and `toCSS()` |\n| `@pierre/highlights/themes/` | One theme as the default export, e.g. `pierre-dark` |\n| `@pierre/highlights/themes/loader` | `themes`, a map from bundled IDs to async module loaders |\n\nPass the resolved object as `theme`; a string ID is not accepted. A\n`ThemeFamily` resolves to its first member. Pass `family.themes[index]` to\nselect another. Theme preparation is cached by object identity; create new\nobjects when changing values.\n\nFor `@pierre/diffs` components, load these objects through\n`registerCustomTheme(name, loader, 'zed')` and select\n`preferredHighlighter: 'highlights'`. See the\n[custom highlighting recipe](../../diffs/references/recipe-custom-highlighting.md)\nfor registration and backend selection.\n\n## Custom themes\n\n```ts\nimport type { Theme } from '@pierre/highlights';\n\nconst theme = {\n name: 'App Dark',\n appearance: 'dark',\n style: {\n 'editor.background': '#101010',\n 'editor.foreground': '#eeeeee',\n syntax: {\n keyword: { color: '#c084fc', font_weight: 700 },\n comment: { color: '#888888', font_style: 'italic' },\n },\n },\n} satisfies Theme;\n```\n\nColors support three-, four-, six-, and eight-digit hex and numeric\n`color(display-p3 ...)` values. Use the CSS-variable mode below for application\nvariables. Syntax scopes such as `keyword.control` inherit from their nearest\nconfigured parent.\n\nTheme types come from `@pierre/highlights`:\n\n| Type | Shape |\n| --------------------- | -------------------------------------------------------------------- |\n| `Theme` | `name`, `appearance`, `style`, and optional `cssVariables: true` |\n| `ThemeFamily` | `themes: readonly Theme[]`, optional `name` and `author` |\n| `ThemeStyle` | Editor colors and `syntax`, plus additional Zed style keys |\n| `ThemeSyntaxSettings` | Optional `color`, `font_style`, and `font_weight` |\n| `ThemePlayer` | Optional collaborator `cursor`, `selection`, and `background` colors |\n| `ThemeOptions` | Exactly one of `theme` or `themes` |\n\nEach `style.syntax` value can be a color string or `ThemeSyntaxSettings`.\n\n## Switch colors with CSS variables\n\n```ts\nimport { codeToHtml } from '@pierre/highlights';\nimport { cssVariables, pierreDark, toCSS } from '@pierre/highlights/themes';\n\nconst cssVariablePrefix = '--code-';\nconst html = new TextDecoder().decode(\n codeToHtml('const answer = 42;', {\n lang: 'ts',\n theme: cssVariables,\n cssVariablePrefix,\n })\n);\nconst stylesheet = `.highlights { ${toCSS(pierreDark, { cssVariablePrefix })} }`;\n```\n\nInclude the stylesheet with the markup. `toCSS(theme, options?)` accepts a\n`Theme` and returns declarations without a selector. Apply them to the code\nblock or an ancestor. Keep its prefix and the highlighting prefix equal; both\ndefault to `--hls-`. Changing declarations updates colors without tokenization.\nThis mode controls colors only and ignores theme font style and weight.\n\n## Multiple themes\n\nAll highlighting and tokenization APIs accept a `themes` map. `defaultColor`\nselects how it renders:\n\n| Value | Result |\n| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- |\n| A theme key | Applies that scheme inline and emits other schemes as custom properties; defaults to `light` and throws if the key is absent |\n| `false` | Emits all schemes as custom properties for CSS to select |\n| `'light-dark()'` | Requires `light` and `dark`; merges colors into CSS `light-dark()` values following the page's `color-scheme` |\n\n```ts\nimport { codeToHtml } from '@pierre/highlights';\nimport { pierreDark, pierreLight } from '@pierre/highlights/themes';\n\nconst html = new TextDecoder().decode(\n codeToHtml('const answer = 42;', {\n lang: 'ts',\n themes: { light: pierreLight, dark: pierreDark },\n defaultColor: false,\n })\n);\n```\n\nInclude CSS to select the emitted properties:\n\n```css\n.highlights {\n color: var(--hls-light);\n background-color: var(--hls-light-bg);\n}\n\n.highlights span {\n color: var(--hls-light);\n font-style: var(--hls-light-font-style, normal);\n font-weight: var(--hls-light-font-weight, normal);\n}\n\n@media (prefers-color-scheme: dark) {\n .highlights {\n color: var(--hls-dark);\n background-color: var(--hls-dark-bg);\n }\n\n .highlights span {\n color: var(--hls-dark);\n font-style: var(--hls-dark-font-style, normal);\n font-weight: var(--hls-dark-font-weight, normal);\n }\n}\n```\n\nFor a custom token renderer, apply each token's complete `htmlStyle` map to its\nspan. With `defaultColor: false`, apply `result.rootStyle` as the container's\ninline style, then use equivalent CSS for that container. With an inline\ndefault, the root style is `background-color:${result.bg};color:${result.fg}`;\nthese fields can include additional declarations. Preserve those declarations\ninstead of treating them as single CSS color values.\n\n## Named CSS palettes\n\nA theme can use `cssVariables: { prefix, defaults }` to map syntax categories to\napplication palette variables while retaining font settings:\n\n```ts\nconst theme = {\n name: 'App palette',\n appearance: 'dark',\n cssVariables: {\n prefix: '--app-',\n defaults: { keyword: '#c084fc' },\n },\n style: {\n syntax: {\n keyword: { color: 'keyword', font_weight: 700 },\n comment: { color: 'muted', font_style: 'italic' },\n },\n },\n} satisfies Theme;\n```\n\nSyntax `color` values are variable suffixes in this mode. Unconfigured syntax\ncategories inherit the `foreground` variable, and defaults become CSS `var()`\nfallbacks. The palette prefix belongs to the theme and is independent of the\nprefix used for multiple theme output. Diffs uses this mode for its portable\n`createCSSVariablesTheme` palette.\n","skills/theme/SKILL.md":"---\nname: theme\ndescription:\n Use when an app needs a Pierre light or dark theme from @pierre/theme for\n Shiki, VS Code, Cursor, or Zed, including soft, vibrant, protanopia,\n deuteranopia, and tritanopia variants.\n---\n\n# `@pierre/theme`\n\nUse `@pierre/theme` for Pierre syntax and editor themes. The package supplies\nten immutable Shiki and VS Code theme objects.\n\nFor Zed-compatible themes used by `@pierre/highlights`, read the\n[highlights skill](../highlights/SKILL.md).\n\n## Install\n\n```bash\npnpm add @pierre/theme\n```\n\n## Select an API reference\n\n| Need | Reference |\n| --------------------------------------- | ---------------------------------------- |\n| List every package entry and export | [API reference](references/api.md) |\n| Compare all themes and select a variant | [Theme variants](references/variants.md) |\n\n## Select a recipe\n\n| Task | Recipe |\n| ----------------------------------- | ------------------------------------------------------- |\n| Load a Pierre theme in Shiki | [Use a theme with Shiki](references/recipe-shiki.md) |\n| Install a Pierre theme in an editor | [Use a theme in an editor](references/recipe-editor.md) |\n\nUse the `theming` skill when the app must switch themes at runtime or follow a\ncolor mode.\n","skills/theme/references/api.md":"# `@pierre/theme` API reference\n\nThis reference lists every public package entry.\n\n## Main entry\n\n| Import | Export | Purpose |\n| --------------- | ------------ | ------------------------------------------- |\n| `@pierre/theme` | `themeNames` | Lists the ten theme names in package order. |\n\n## Theme entries\n\nEach entry has one default export. The export is an immutable Pierre theme\nobject.\n\n| Import | Theme name | Color scheme | Purpose |\n| ---------------------------------------------------- | -------------------------------------- | ------------ | ---------------------------------------------------- |\n| `@pierre/theme/pierre-light` | `pierre-light` | Light | Supplies the standard light theme. |\n| `@pierre/theme/pierre-dark` | `pierre-dark` | Dark | Supplies the standard dark theme. |\n| `@pierre/theme/pierre-light-soft` | `pierre-light-soft` | Light | Supplies the soft light theme. |\n| `@pierre/theme/pierre-dark-soft` | `pierre-dark-soft` | Dark | Supplies the soft dark theme. |\n| `@pierre/theme/pierre-light-vibrant` | `pierre-light-vibrant` | Light | Supplies the Display-P3 light theme. |\n| `@pierre/theme/pierre-dark-vibrant` | `pierre-dark-vibrant` | Dark | Supplies the Display-P3 dark theme. |\n| `@pierre/theme/pierre-light-protanopia-deuteranopia` | `pierre-light-protanopia-deuteranopia` | Light | Supplies the light red-green color-vision variant. |\n| `@pierre/theme/pierre-dark-protanopia-deuteranopia` | `pierre-dark-protanopia-deuteranopia` | Dark | Supplies the dark red-green color-vision variant. |\n| `@pierre/theme/pierre-light-tritanopia` | `pierre-light-tritanopia` | Light | Supplies the light blue-yellow color-vision variant. |\n| `@pierre/theme/pierre-dark-tritanopia` | `pierre-dark-tritanopia` | Dark | Supplies the dark blue-yellow color-vision variant. |\n\n## Raw theme entries\n\n`@pierre/theme/themes/*` exposes each generated JSON file. Replace `*` with a\ntheme file name, including `.json`.\n\n## Theme object\n\nEach default export has these immutable fields:\n\n| Field | Purpose |\n| --------------------- | ---------------------------------------------- |\n| `name` | Provides the stable theme identifier. |\n| `displayName` | Provides the label for a theme selector. |\n| `type` | Identifies the `light` or `dark` color scheme. |\n| `colors` | Maps VS Code workbench color keys to colors. |\n| `tokenColors` | Defines TextMate token styles. |\n| `semanticTokenColors` | Defines semantic token styles. |\n","skills/theme/references/recipe-editor.md":"# Recipe: use a Pierre theme in an editor\n\n## VS Code or Cursor\n\n1. Install the **Pierre Theme** extension from the editor marketplace.\n2. Open the color theme selector.\n3. Select a `Pierre` theme.\n\n## Zed\n\n1. Install the **Pierre** extension from the Zed extension registry.\n2. Open the theme selector.\n3. Select a `Pierre` theme.\n\nThe editor extensions include the standard, soft, protanopia and deuteranopia,\nand tritanopia treatments.\n","skills/theme/references/recipe-shiki.md":"# Recipe: use a Pierre theme with Shiki\n\nInstall the package:\n\n```bash\npnpm add @pierre/theme shiki\n```\n\nImport the theme object and pass it to Shiki:\n\n```ts\nimport pierreDark from '@pierre/theme/pierre-dark';\nimport { codeToHtml } from 'shiki';\n\nconst html = await codeToHtml(source, {\n lang: 'typescript',\n theme: pierreDark,\n});\n```\n\nImport a matching light and dark pair when the app supports both color schemes.\nUse the `theming` skill when the user can change the active theme at runtime.\n","skills/theme/references/variants.md":"# Pierre theme variants\n\nSelect one treatment and use its light and dark entries as a pair.\n\n| Treatment | Light entry | Dark entry | Select it for |\n| --------------------------- | -------------------------------------- | ------------------------------------- | ----------------------------------------- |\n| Standard | `pierre-light` | `pierre-dark` | The default Pierre appearance. |\n| Soft | `pierre-light-soft` | `pierre-dark-soft` | A lower-contrast appearance. |\n| Vibrant | `pierre-light-vibrant` | `pierre-dark-vibrant` | Display-P3 output in Shiki or a web page. |\n| Protanopia and deuteranopia | `pierre-light-protanopia-deuteranopia` | `pierre-dark-protanopia-deuteranopia` | Red-green color-vision support. |\n| Tritanopia | `pierre-light-tritanopia` | `pierre-dark-tritanopia` | Blue-yellow color-vision support. |\n\nThe editor extensions include the eight sRGB themes. The vibrant themes use CSS\nDisplay-P3 color syntax and target web output.\n\nUse the standard pair unless the product specifies another treatment. Use the\nsame treatment for both color schemes.\n","skills/theming/SKILL.md":"---\nname: theming\ndescription:\n Use when an app uses @pierre/theming to list, resolve, select, switch,\n persist, or apply themes, including color modes, theme controllers, React\n state, UI colors, and bundled Pierre or Shiki collections.\n---\n\n# `@pierre/theming`\n\nUse `@pierre/theming` to manage runtime themes. The package separates theme\nmetadata, theme resolution, selected state, and UI color mapping.\n\n## Install\n\n```bash\npnpm add @pierre/theming\n```\n\nInstall optional peer dependencies only for the selected entry. The React entry\nneeds `react`. The themes entry needs `@pierre/theme`, `@shikijs/themes`, and\n`shiki`.\n\n## Select an API reference\n\n| Need | Reference |\n| -------------------------------------------------------------- | -------------------------------------------- |\n| Create a collection, catalog, descriptor, or bundled theme set | [Collections API](references/collections.md) |\n| Register, load, seed, or cache theme objects | [Resolver API](references/resolver.md) |\n| Track the color mode and selected light and dark themes | [Controller API](references/controller.md) |\n| Normalize workbench colors or derive colors | [Colors API](references/colors.md) |\n| Read controller state in React | [React API](references/react.md) |\n\n## Select a controller recipe\n\n| Situation | Recipe |\n| ---------------------------------------------------------------------------- | --------------------------------------------------------------------- |\n| One app or page shares one color mode and one light/dark selection | [Use one controller](references/recipe-one-controller.md) |\n| Independent areas need separate selections or separate controller lifecycles | [Use multiple controllers](references/recipe-multiple-controllers.md) |\n\nUse one controller by default. Use multiple controllers only when the theme\nstate must differ between areas.\n\n## Select a framework recipe\n\n| Host | Recipe |\n| --------------------------------------- | ------------------------------------------------------ |\n| Vanilla JavaScript or another framework | [Use vanilla JavaScript](references/recipe-vanilla.md) |\n| React | [Use React](references/recipe-react.md) |\n","skills/theming/references/collections.md":"# Collections API\n\nThis reference covers collection APIs from `@pierre/theming` and all exports\nfrom `@pierre/theming/themes`.\n\n## `@pierre/theming` exports\n\n| Export | Kind | Purpose |\n| --------------------------- | -------- | ------------------------------------------------------------------ |\n| `createThemeCollection` | Function | Creates an immutable ordered set of theme descriptors. |\n| `ThemeCollection` | Type | Defines collection queries, transforms, and resolver registration. |\n| `ThemeCollectionComparator` | Type | Compares two descriptors for `orderBy`. |\n| `ThemeCollectionEntry` | Type | Accepts one descriptor or collection source. |\n| `ThemeCollectionFilter` | Type | Filters by `collection` and `colorScheme`. |\n| `ThemeCollectionInput` | Type | Accepts one entry or an iterable of entries. |\n| `ThemeCollectionSource` | Type | Defines an object that returns theme descriptors. |\n| `ThemeDescriptor` | Type | Describes one named theme and its lazy loader. |\n| `createThemeCatalog` | Function | Creates a collection with default light and dark theme names. |\n| `ThemeCatalog` | Type | Adds default theme names to `ThemeCollection`. |\n\n## `ThemeDescriptor` fields\n\n| Field | Purpose |\n| ------------- | --------------------------------------- |\n| `name` | Stores the stable theme identifier. |\n| `load` | Loads the theme object. |\n| `colorScheme` | Labels the descriptor as light or dark. |\n| `collection` | Groups related themes. |\n| `displayName` | Supplies a user-facing label. |\n\n## `ThemeCollection` methods\n\n| Method | Purpose |\n| ------------------------ | ---------------------------------------------------- |\n| `getTheme(name)` | Gets one descriptor by name. |\n| `getThemes(filter?)` | Lists descriptors that match an optional filter. |\n| `getThemeNames(filter?)` | Lists names that match an optional filter. |\n| `hasTheme(name)` | Tests whether the collection has a name. |\n| `orderBy(compare)` | Returns a new collection in comparator order. |\n| `pick(names)` | Returns a new collection in the supplied name order. |\n| `registerInto(resolver)` | Adds every descriptor loader to a resolver. |\n\n## `ThemeCatalog` fields\n\n| Field | Purpose |\n| ----------------------- | ------------------------------ |\n| `defaultLightThemeName` | Names the initial light theme. |\n| `defaultDarkThemeName` | Names the initial dark theme. |\n\n## `@pierre/theming/themes` exports\n\n| Export | Kind | Purpose |\n| -------------------- | -------- | ----------------------------------------------------------------------------- |\n| `themes` | Value | Combines the Pierre and Shiki collections in stable order. |\n| `pierreThemes` | Value | Provides lazy descriptors for the ten Pierre themes. |\n| `shikiThemes` | Value | Provides lazy descriptors for the bundled Shiki themes. |\n| `createTheme` | Function | Creates a descriptor whose loader normalizes a raw Shiki or VS Code theme. |\n| `CreateThemeOptions` | Type | Defines the name, loader, and optional descriptor metadata for `createTheme`. |\n\nUse `createTheme` for a raw Shiki or VS Code theme. Use a `ThemeDescriptor`\ndirectly when the loader already returns a compatible `ThemeLike` object.\n","skills/theming/references/colors.md":"# Colors API\n\nThis reference covers every export from `@pierre/theming/color`.\n\n## Exports\n\n| Export | Kind | Purpose |\n| ---------------------- | -------- | -------------------------------------------------------------- |\n| `normalizeThemeColors` | Function | Resolves the UI color fallback chains in a `ThemeLike` object. |\n| `colorUtils` | Object | Groups pure color checks and transforms. |\n\n`normalizeThemeColors(theme)` returns a memoized `ThemeLike` object. Use its\n`colors` map for the UI around syntax-highlighted code.\n\n## `colorUtils` methods\n\n| Method | Purpose |\n| ---------------------------------------------------- | -------------------------------------------------------------- |\n| `relativeLuminance(color)` | Calculates WCAG luminance for a hex color. |\n| `contrastRatio(a, b)` | Calculates the contrast ratio between two luminance values. |\n| `compositeOverBg(foreground, background?)` | Flattens a translucent hex color over a background. |\n| `isFullyTransparent(color?)` | Tests whether a hex color has zero alpha. |\n| `isDarkSurface(background?, foregroundHint?)` | Classifies a surface as dark or light. |\n| `surfacesMatch(a?, b?)` | Tests whether two hex surfaces produce the same visible color. |\n| `hoverWouldEraseText(hover, background, foreground)` | Tests whether a hover surface removes text contrast. |\n| `pickReadableForeground(background, candidates)` | Selects the candidate with the best readable contrast. |\n| `deriveMutedFg(foreground, background)` | Derives a muted foreground with readable contrast. |\n\nThe color methods measure hex colors. A method returns its documented empty\nresult when it cannot measure another CSS color format.\n","skills/theming/references/controller.md":"# Controller API\n\nThis reference covers controller and shared theme types from `@pierre/theming`.\n\n## Exports\n\n| Export | Kind | Purpose |\n| ----------------------------- | -------- | ------------------------------------------------------------------ |\n| `createThemeController` | Function | Creates state for a color mode and selected light and dark themes. |\n| `ThemeController` | Type | Defines controller state, mutations, subscription, and cleanup. |\n| `ThemeControllerOptions` | Type | Selects a catalog or resolver and configures initial state. |\n| `ThemeControllerState` | Type | Describes the current selection and resolved theme. |\n| `PendingThemeResolution` | Type | Identifies the active theme load. |\n| `ThemeResolutionError` | Type | Describes a failed active theme load. |\n| `ThemeResolutionErrorContext` | Type | Identifies the name and scheme for a failed load callback. |\n| `ThemePersistence` | Type | Defines custom `load` and `save` methods. |\n| `ThemeSelection` | Type | Describes the persisted mode and theme names. |\n| `ColorMode` | Type | Accepts `light`, `dark`, or `system`. |\n| `ColorScheme` | Type | Accepts concrete `light` or `dark`. |\n| `ThemeLike` | Type | Defines the shared resolved-theme shape. |\n\n## `ThemeControllerOptions` fields\n\n| Field | Purpose |\n| ----------------------- | ------------------------------------------------------------------- |\n| `catalog` | Supplies descriptors and catalog default names. |\n| `resolver` | Supplies an existing resolver or shares one with other controllers. |\n| `defaultLightThemeName` | Overrides the initial light theme name. |\n| `defaultDarkThemeName` | Overrides the initial dark theme name. |\n| `defaultMode` | Sets the initial color mode. |\n| `storageKey` | Stores the selection in browser local storage. |\n| `persistence` | Supplies custom selection storage. |\n| `preloadInactive` | Resolves the inactive color-scheme theme too. |\n| `onResolutionError` | Receives an active theme load error. |\n\nPass a `catalog`, a `resolver`, or a catalog with a shared resolver.\n\n## `ThemeController` members\n\n| Member | Purpose |\n| ------------------------------------- | ---------------------------------------------------------------- |\n| `resolver` | Exposes the controller's resolver. |\n| `getState()` | Returns the current immutable state object. |\n| `setColorMode(mode)` | Selects light, dark, or system mode. |\n| `setThemeNameForScheme(scheme, name)` | Selects the theme for one color scheme. |\n| `subscribe(listener)` | Subscribes to state changes and returns an unsubscribe function. |\n| `destroy()` | Removes the system color-scheme listener. |\n\n## `ThemeControllerState` fields\n\n| Field | Purpose |\n| ------------------------ | -------------------------------------------------- |\n| `lightThemeName` | Stores the selected light theme name. |\n| `darkThemeName` | Stores the selected dark theme name. |\n| `mode` | Stores the selected color mode. |\n| `resolvedColorScheme` | Provides the active concrete light or dark scheme. |\n| `resolvedTheme` | Provides the active resolved theme object. |\n| `pendingThemeResolution` | Identifies an active theme load. |\n| `resolutionError` | Describes the latest active load failure. |\n","skills/theming/references/react.md":"# React API\n\nThis reference lists every export from `@pierre/theming/react`.\n\n| Export | Kind | Purpose |\n| -------------------- | ---- | ------------------------------------------------------------------------- |\n| `useThemeController` | Hook | Subscribes to a `ThemeController` and returns its `ThemeControllerState`. |\n\nThe hook uses the controller state for both client and server snapshots. Create\nthe controller outside the component that reads it.\n","skills/theming/references/recipe-multiple-controllers.md":"# Recipe: use multiple theme controllers\n\nUse multiple controllers when independent areas need different modes,\nselections, storage, or lifecycles. Share one resolver when those areas use the\nsame theme loaders and cache.\n\n```ts\nimport {\n createThemeCatalog,\n createThemeController,\n createThemeResolver,\n} from '@pierre/theming';\nimport { themes } from '@pierre/theming/themes';\n\nconst catalog = createThemeCatalog({\n themes,\n defaultLightThemeName: 'pierre-light',\n defaultDarkThemeName: 'pierre-dark',\n});\n\nconst resolver = createThemeResolver();\n\nexport const workspaceTheme = createThemeController({\n catalog,\n resolver,\n storageKey: 'workspace-theme',\n});\n\nexport const previewTheme = createThemeController({\n catalog,\n resolver,\n defaultMode: 'light',\n storageKey: 'preview-theme',\n});\n```\n\nSubscribe each area to its own controller. Call `destroy()` on each controller\nwhen its area is removed. Use distinct storage keys when selections must remain\nindependent.\n","skills/theming/references/recipe-one-controller.md":"# Recipe: use one theme controller\n\nUse one controller when the app shares one color mode and one light/dark theme\nselection.\n\nCreate the catalog and controller in one module:\n\n```ts\nimport { createThemeCatalog, createThemeController } from '@pierre/theming';\nimport { themes } from '@pierre/theming/themes';\n\nexport const themeCatalog = createThemeCatalog({\n themes,\n defaultLightThemeName: 'pierre-light',\n defaultDarkThemeName: 'pierre-dark',\n});\n\nexport const themeController = createThemeController({\n catalog: themeCatalog,\n defaultMode: 'system',\n storageKey: 'app-theme',\n});\n```\n\nImport the same controller wherever the app reads or changes theme state. Call\n`destroy()` when the application tears down the controller module.\n","skills/theming/references/recipe-react.md":"# Recipe: use a theme controller in React\n\nCreate the controller in a module. Read it with `useThemeController`:\n\n```tsx\nimport { useEffect } from 'react';\nimport { useThemeController } from '@pierre/theming/react';\n\nimport { themeController } from './theme-controller';\n\nexport function ThemeControls() {\n const state = useThemeController(themeController);\n\n useEffect(() => {\n document.documentElement.dataset.colorScheme = state.resolvedColorScheme;\n }, [state.resolvedColorScheme]);\n\n return (\n \n themeController.setColorMode(\n state.resolvedColorScheme === 'dark' ? 'light' : 'dark'\n )\n }\n >\n Use {state.resolvedColorScheme === 'dark' ? 'light' : 'dark'} mode\n \n );\n}\n```\n\nPass `state.resolvedTheme` to code or tree surfaces. Use `normalizeThemeColors`\nwhen a React component needs workbench UI colors.\n","skills/theming/references/recipe-vanilla.md":"# Recipe: use a theme controller in vanilla JavaScript\n\nCreate a controller with the one-controller or multiple-controller recipe. Apply\neach state change to the document:\n\n```ts\nimport { normalizeThemeColors } from '@pierre/theming/color';\nimport { themeController } from './theme-controller';\n\nfunction applyTheme() {\n const state = themeController.getState();\n document.documentElement.dataset.colorScheme = state.resolvedColorScheme;\n\n if (state.resolvedTheme == null) return;\n const { colors } = normalizeThemeColors(state.resolvedTheme);\n document.documentElement.style.setProperty(\n '--app-background',\n colors?.['editor.background'] ?? state.resolvedTheme.bg ?? ''\n );\n document.documentElement.style.setProperty(\n '--app-foreground',\n colors?.['editor.foreground'] ?? state.resolvedTheme.fg ?? ''\n );\n}\n\napplyTheme();\nconst unsubscribe = themeController.subscribe(applyTheme);\n```\n\nCall `themeController.setColorMode(mode)` from a mode control. Call\n`setThemeNameForScheme(scheme, name)` from a theme selector. Call\n`unsubscribe()` when the host no longer needs updates.\n","skills/theming/references/resolver.md":"# Resolver API\n\nThis reference covers the resolver exports from `@pierre/theming`.\n\n## Exports\n\n| Export | Kind | Purpose |\n| ------------------------ | -------- | ------------------------------------------------------------- |\n| `createThemeResolver` | Function | Creates an isolated loader registry and resolved-theme cache. |\n| `ThemeResolver` | Type | Defines the resolver methods. |\n| `ThemeLoader` | Type | Defines an asynchronous theme loader. |\n| `DuplicateThemeError` | Class | Reports a second registration for the same name. |\n| `UnregisteredThemeError` | Class | Reports a resolve request for a name with no loader. |\n| `UnresolvedThemeError` | Class | Reports a synchronous batch read with an unresolved name. |\n\n## `ThemeResolver` methods\n\n| Method | Purpose |\n| ------------------------------------- | -------------------------------------------------------- |\n| `registerTheme(name, loader)` | Registers one loader. |\n| `registerThemeIfAbsent(name, loader)` | Registers one loader only when the name is free. |\n| `hasRegisteredTheme(name)` | Tests whether a loader exists. |\n| `resolveTheme(name)` | Loads and caches one theme. |\n| `resolveThemes(names)` | Loads and caches themes in input order. |\n| `getResolvedTheme(name)` | Reads one cached theme or returns `undefined`. |\n| `getResolvedThemes(names)` | Reads cached themes in input order. |\n| `getResolvedOrResolveTheme(name)` | Returns a cached theme or starts its load. |\n| `hasResolvedTheme(name)` | Tests whether one cached theme exists. |\n| `hasResolvedThemes(names)` | Tests whether all named themes exist in the cache. |\n| `seedResolvedTheme(name, theme)` | Adds one resolved object without a loader. |\n| `seedResolvedThemes(entries)` | Adds several resolved objects without loaders. |\n| `clearResolvedThemes()` | Clears cached themes and active loads but keeps loaders. |\n\nEach loader returns a `ThemeLike` object or a module object with that value on\n`default`.\n\n## Fallback loading and normalization\n\n`createThemeResolver(options?)` accepts `ThemeResolverOptions`:\n\n```ts\nconst resolver = createThemeResolver({\n fallbackLoader: async (name) => {\n const loader = bundledLoaders[name];\n return loader === undefined ? undefined : loader();\n },\n normalizeTheme: (theme, name) => ({ ...theme, name }),\n});\n```\n\nExplicit registrations take precedence over `fallbackLoader`. A fallback may\nreturn a theme, a `{ default: theme }` module, or `undefined` for an unknown\nname. `normalizeTheme(theme, name)` can be synchronous or asynchronous and runs\nbefore successful loads enter the cache. Seeded values are already normalized.\nConcurrent calls share fallback loading and normalization; rejected loads can be\nretried. Clearing caches prevents an earlier in-flight load from repopulating\nthem. The core resolver still imports no backend or bundled theme data.\n","skills/trees/SKILL.md":"","skills/trees/references/api-core.md":"# Core API\n\nThis reference lists every export from `@pierre/trees` and every public\n`FileTree` member.\n\n## Contents\n\n- [Runtime values](#runtime-values)\n- [`FileTree` members](#filetree-members)\n- [Configuration and state types](#configuration-and-state-types)\n- [Mutation types](#mutation-types)\n- [Interaction types](#interaction-types)\n- [Presentation types](#presentation-types)\n- [Constants](#constants)\n\n## Runtime values\n\n| Export | Kind | Purpose |\n| ------------------------------- | -------- | ----------------------------------------------------------------- |\n| `FileTree` | Class | Owns the tree model, renders it, and exposes path-based controls. |\n| `prepareFileTreeInput` | Function | Prepares and optionally sorts a path list for reuse. |\n| `preparePresortedFileTreeInput` | Function | Prepares a path list that already has final order. |\n| `preloadFileTree` | Function | Creates server-rendered tree markup and hydration data. |\n| `serializeFileTreeSsrPayload` | Function | Joins an SSR payload into one host markup string. |\n| `themeToTreeStyles` | Function | Maps a resolved theme to tree host CSS properties. |\n| `getBuiltInSpriteSheet` | Function | Gets the SVG sprite for a built-in icon set. |\n| `createFileTreeIconResolver` | Function | Creates an icon resolver from an icon configuration. |\n\n## `FileTree` members\n\n| Member | Purpose |\n| -------------------------------- | ----------------------------------------------------------- |\n| `new FileTree(options)` | Creates a model from paths or prepared input. |\n| `FileTree.LoadedCustomComponent` | Reports whether the file-tree custom element module loaded. |\n| `render(props)` | Mounts the tree into a wrapper or host element. |\n| `hydrate(props)` | Attaches the model to preloaded host markup. |\n| `unmount()` | Removes the mounted view and keeps the model. |\n| `cleanUp()` | Removes the view and destroys model resources. |\n| `getFileTreeContainer()` | Gets the mounted host element. |\n| `getItem(path)` | Gets a path handle or `null`. |\n| `getFocusedItem()` | Gets the focused item handle or `null`. |\n| `getFocusedPath()` | Gets the focused path or `null`. |\n| `getSelectedPaths()` | Gets the selected paths. |\n| `getComposition()` | Gets the current header and context-menu configuration. |\n| `getItemHeight()` | Gets the resolved row height. |\n| `getDensityFactor()` | Gets the resolved density factor. |\n| `subscribe(listener)` | Subscribes to model changes. |\n| `focusPath(path)` | Focuses a path. |\n| `focusNearestPath(path)` | Focuses and returns the nearest available path. |\n| `scrollToPath(path, options?)` | Scrolls a path into view. |\n| `add(path)` | Adds one path. |\n| `remove(path, options?)` | Removes one path. |\n| `move(from, to, options?)` | Moves one path. |\n| `batch(operations)` | Applies several path mutations together. |\n| `resetPaths(paths, options?)` | Replaces the full path set. |\n| `onMutation(type, handler)` | Subscribes to mutation events. |\n| `setSearch(value)` | Sets or clears the search query. |\n| `openSearch(initialValue?)` | Opens the search session. |\n| `closeSearch()` | Closes the search session. |\n| `isSearchOpen()` | Tests whether search is open. |\n| `getSearchValue()` | Gets the search query. |\n| `getSearchMatchingPaths()` | Gets paths that match the query. |\n| `focusNextSearchMatch()` | Focuses the next search match. |\n| `focusPreviousSearchMatch()` | Focuses the previous search match. |\n| `startRenaming(path?, options?)` | Starts inline rename and reports whether it started. |\n| `setGitStatus(status?)` | Replaces all git status entries. |\n| `applyGitStatusPatch(patch)` | Applies a partial git status update. |\n| `setIcons(icons?)` | Replaces the icon configuration. |\n| `setComposition(composition?)` | Replaces header and context-menu configuration. |\n\n## Configuration and state types\n\n| Export | Purpose |\n| -------------------------- | --------------------------------------------------------------- |\n| `FileTreeOptions` | Defines input, behavior, rendering, and presentation options. |\n| `FileTreePreparedInput` | Holds a reusable prepared path list. |\n| `FileTreeInitialExpansion` | Selects closed, open, or depth-based initial expansion. |\n| `FileTreeSortComparator` | Compares two path entries. |\n| `FileTreeSortEntry` | Describes one path for a sort comparator. |\n| `FileTreeRenderOptions` | Configures row height, row count, overscan, and sticky folders. |\n| `FileTreeRenderProps` | Selects the wrapper or existing host for `render`. |\n| `FileTreeHydrationProps` | Selects the host for `hydrate`. |\n| `FileTreeVisibleRow` | Describes one visible tree row. |\n| `FileTreeItemHandle` | Represents a file or directory item. |\n| `FileTreeFileHandle` | Controls one file item. |\n| `FileTreeDirectoryHandle` | Controls one directory item and its expansion. |\n| `FileTreeListener` | Defines a model subscription callback. |\n| `FileTreeSsrPayload` | Holds the host and shadow markup for server output. |\n\n## Mutation types\n\n| Export | Purpose |\n| ----------------------------------- | -------------------------------------------------------------- |\n| `FileTreeMutationHandle` | Defines the public path mutation methods. |\n| `FileTreeBatchOperation` | Describes one add, remove, or move in a batch. |\n| `FileTreeCollisionStrategy` | Selects error, replace, or skip behavior for a move collision. |\n| `FileTreeMoveOptions` | Configures move collision behavior. |\n| `FileTreeRemoveOptions` | Configures recursive removal. |\n| `FileTreeResetOptions` | Configures a path reset and optional prepared input. |\n| `FileTreeResetPreparedOptions` | Configures a reset that uses prepared input. |\n| `FileTreeMutationEvent` | Represents any mutation event. |\n| `FileTreeMutationSemanticEvent` | Represents an add, remove, move, or reset event. |\n| `FileTreeMutationEventType` | Names a mutation operation. |\n| `FileTreeMutationEventForType` | Selects the event shape for an operation name. |\n| `FileTreeMutationEventInvalidation` | Describes the state invalidation from a mutation. |\n| `FileTreeAddEvent` | Describes one add result. |\n| `FileTreeRemoveEvent` | Describes one remove result. |\n| `FileTreeMoveEvent` | Describes one move result. |\n| `FileTreeResetEvent` | Describes one reset result. |\n| `FileTreeBatchEvent` | Describes one batch result. |\n\n## Interaction types\n\n| Export | Purpose |\n| --------------------------------- | -------------------------------------------------- |\n| `FileTreeSelectionChangeListener` | Receives the selected path list. |\n| `FileTreeSearchChangeListener` | Receives the current search query. |\n| `FileTreeSearchSessionHandle` | Defines search session methods. |\n| `FileTreeSearchMode` | Selects how nonmatching rows appear. |\n| `FileTreeSearchBlurBehavior` | Selects search behavior after focus leaves. |\n| `FileTreeScrollOffset` | Selects top, center, or nearest scroll alignment. |\n| `FileTreeScrollToPathOptions` | Configures focus and alignment for `scrollToPath`. |\n| `FileTreeDragAndDropConfig` | Configures drag rules and completion callbacks. |\n| `FileTreeDropTarget` | Describes the current drop target. |\n| `FileTreeDropContext` | Describes dragged paths and their target. |\n| `FileTreeDropResult` | Describes the completed move or batch operation. |\n| `FileTreeRenamingConfig` | Configures rename rules and callbacks. |\n| `FileTreeRenamingItem` | Describes the item offered to a rename rule. |\n| `FileTreeRenameEvent` | Describes a completed rename. |\n\n## Presentation types\n\n| Export | Purpose |\n| ---------------------------------- | ----------------------------------------------------------- |\n| `FileTreeCompositionOptions` | Configures header and context-menu composition. |\n| `FileTreeHeaderCompositionOptions` | Supplies header HTML or a header renderer. |\n| `ContextMenuItem` | Describes the file or directory for a context menu. |\n| `ContextMenuOpenContext` | Supplies menu position, close, and focus controls. |\n| `ContextMenuAnchorRect` | Describes the menu anchor rectangle. |\n| `ContextMenuTriggerMode` | Selects right-click, button, or both triggers. |\n| `ContextMenuButtonVisibility` | Selects when the row menu button appears. |\n| `FileTreeRowDecoration` | Describes text or icon content in the decoration lane. |\n| `FileTreeRowDecorationContext` | Supplies the item and visible row to a decoration renderer. |\n| `FileTreeRowDecorationRenderer` | Produces one row decoration. |\n| `GitStatus` | Names a supported git status. |\n| `GitStatusEntry` | Assigns a git status to one path. |\n| `FileTreeGitStatusPatch` | Adds, changes, or removes git status entries. |\n| `FileTreeBuiltInIconSet` | Names a built-in icon set. |\n| `FileTreeIconConfig` | Configures built-in and custom icon rules. |\n| `FileTreeIcons` | Accepts an icon set name or icon configuration. |\n| `RemappedIcon` | Names or defines a replacement SVG symbol. |\n| `FileTreeDensity` | Accepts a density keyword or numeric factor. |\n| `FileTreeDensityKeyword` | Names compact, default, or relaxed density. |\n| `FileTreeDensityPreset` | Holds a density factor and row height. |\n| `TreeThemeInput` | Defines the resolved theme accepted by `themeToTreeStyles`. |\n| `TreeThemeStyles` | Maps tree CSS property names to values. |\n\n## Constants\n\n| Export | Purpose |\n| ---------------------------------------------- | --------------------------------------------------------------- |\n| `FILE_TREE_TAG_NAME` | Provides the `file-tree-container` element name. |\n| `FILE_TREE_STYLE_ATTRIBUTE` | Provides the core style marker attribute. |\n| `FILE_TREE_UNSAFE_CSS_ATTRIBUTE` | Provides the custom style marker attribute. |\n| `FILE_TREE_SCROLLBAR_MEASURE_ATTRIBUTE` | Provides the scrollbar measurement attribute. |\n| `FILE_TREE_SCROLLBAR_GUTTER_STYLE_ATTRIBUTE` | Provides the measured scrollbar style attribute. |\n| `FILE_TREE_SCROLLBAR_GUTTER_MEASURED_PROPERTY` | Provides the measured scrollbar CSS property. |\n| `FILE_TREE_DEFAULT_ITEM_HEIGHT` | Provides the default row height. |\n| `FILE_TREE_DENSITY_PRESETS` | Maps each density keyword to its preset. |\n| `FLATTENED_PREFIX` | Provides the identifier prefix for a flattened directory chain. |\n| `HEADER_SLOT_NAME` | Provides the header slot name. |\n| `CONTEXT_MENU_SLOT_NAME` | Provides the context-menu slot name. |\n| `CONTEXT_MENU_TRIGGER_TYPE` | Provides the context-menu trigger type. |\n","skills/trees/references/api-react.md":"# React API\n\nThis reference lists every export from `@pierre/trees/react`.\n\n| Export | Kind | Purpose |\n| -------------------------- | --------- | ---------------------------------------------------------------------- |\n| `FileTree` | Component | Mounts a `FileTree` model in a React host element. |\n| `FileTreeProps` | Type | Defines the model, header, context menu, preload data, and host props. |\n| `FileTreePreloadedData` | Type | Selects the `id` and `shadowHtml` fields for hydration. |\n| `useFileTree` | Hook | Creates one stable `FileTree` model. |\n| `UseFileTreeResult` | Type | Holds the model returned by `useFileTree`. |\n| `useFileTreeSelection` | Hook | Returns the selected path list and updates with the model. |\n| `useFileTreeSearch` | Hook | Returns search state and search actions. |\n| `FileTreeSearchState` | Type | Defines the search snapshot and actions. |\n| `useFileTreeSelector` | Hook | Subscribes to a selected part of model state. |\n| `FileTreeSelector` | Type | Selects a value from a model. |\n| `FileTreeSelectorEquality` | Type | Compares two selected values. |\n\n`FileTreeProps` extends React host attributes except `children`. Its specific\nfields are:\n\n| Field | Purpose |\n| ------------------- | --------------------------------------------------- |\n| `model` | Supplies the required `FileTree` model. |\n| `header` | Supplies React content for the header slot. |\n| `renderContextMenu` | Produces React content for the active context menu. |\n| `preloadedData` | Supplies server markup for hydration. |\n","skills/trees/references/api-ssr.md":"# SSR API\n\nThis reference lists every export from `@pierre/trees/ssr`.\n\n| Export | Kind | Purpose |\n| ----------------------------- | -------- | --------------------------------------------------------------- |\n| `preloadFileTree` | Function | Renders a tree to a `FileTreeSsrPayload`. |\n| `serializeFileTreeSsrPayload` | Function | Creates declarative or DOM-inserted host markup from a payload. |\n| `FileTreeSsrPayload` | Type | Holds the host start, shadow HTML, host end, and stable ID. |\n\n`preloadFileTree` and `serializeFileTreeSsrPayload` are also available from\n`@pierre/trees`.\n","skills/trees/references/api-web-components.md":"# Web components API\n\nImport `@pierre/trees/web-components` to register the `file-tree-container`\ncustom element. The entry exports these APIs:\n\n| Export | Kind | Purpose |\n| --------------------------- | -------- | ------------------------------------------------------------------------- |\n| `FileTreeContainerLoaded` | Value | Confirms that the registration module ran. |\n| `adoptDeclarativeShadowDom` | Function | Copies a declarative template into an empty shadow root. |\n| `ensureFileTreeStyles` | Function | Installs the core tree stylesheet in a shadow root. |\n| `prepareFileTreeShadowRoot` | Function | Adopts server markup, installs styles, and measures the scrollbar gutter. |\n","skills/trees/references/recipe-interactions.md":"","skills/trees/references/recipe-react.md":"","skills/trees/references/recipe-ssr.md":"","skills/trees/references/recipe-theme.md":"","skills/trees/references/recipe-vanilla.md":""},"files":{".agents/skills/browser-automation/SKILL.md":"---\nname: browser-automation\ndescription:\n Use when opening, inspecting, clicking, filling, snapshotting, or otherwise\n automating web pages for this repo, including local dev servers and\n browser-based verification.\n---\n\n# Browser Automation\n\nUse `agent-browser` for web automation in this repo. Run:\n\n```bash\nagent-browser --help\n```\n\nCore workflow:\n\n```bash\nagent-browser open \nagent-browser snapshot -i\nagent-browser click @e1\nagent-browser fill @e2 \"text\"\n```\n\nRe-run `agent-browser snapshot -i` after page changes so element refs stay\ncurrent.\n\nUse browser automation for behavior that needs a rendered page, real DOM state,\nor interactive verification. Prefer focused Bun tests for pure logic and\nnon-browser integration behavior.\n",".agents/skills/testing-and-verification/SKILL.md":"---\nname: testing-and-verification\ndescription:\n Use when adding or running tests, checking snapshots, choosing between Bun\n tests and Playwright, running lint/format/typecheck, or deciding the\n verification scope for a change.\n---\n\n# Testing and Verification\n\n## Baseline Commands\n\nAfter code changes, run the required baseline (moon tasks run from anywhere in\nthe repo, including CI-marked agent shells):\n\n```bash\nmoon run root:format root:lint\n```\n\nUseful check/fix pairs on the root project:\n\n```bash\nmoon run root:format-check\nmoon run root:format\nmoon run root:lint\nmoon run root:lint-fix\nmoon run root:lint-css\nmoon run root:lint-css-fix\n```\n\nFor code changes, also run the relevant typecheck (moon builds workspace\ndependencies first automatically):\n\n```bash\nmoonx :typecheck\n# or, scoped to what actually changed:\nmoonx :typecheck --affected\n```\n\nThe React Compiler lint rules (`react/*` in `.oxlintrc.json`) assume React.\n`packages/trees/src/render/**/*.tsx` and\n`packages/trees/src/components/**/*.tsx` are Preact, so an `overrides` entry\nthere turns `react/refs` off for those globs. Put new Preact components under\nthose directories instead of adding per-file `oxlint-disable` headers.\n\n## Unit and Integration Tests\n\nUse Bun's built-in test runner. Tests usually live in a `test/` folder inside\neach package and use `describe`, `test`, and `expect` from `bun:test`.\n\nPrefer unit or integration tests by default:\n\n```bash\nmoonx diffs:test\nmoonx trees:test\n```\n\n`moon run :test` runs every project's suite. Tests import workspace dependencies\nthrough their built dist, so moon builds those first; running `bun test`\ndirectly inside a package also works when dist is fresh.\n\n## Snapshots\n\nBun supports `toMatchSnapshot()`. Avoid new snapshot coverage unless it is\nshallow and narrowly scoped to the exact behavior under test.\n\nUpdate snapshots from the package directory:\n\n```bash\nbun test -u\n```\n\n## Browser and E2E Tests\n\nAdd Playwright/browser E2E tests only when behavior cannot be validated without\na real browser engine. Good candidates include computed style checks, shadow DOM\nboundaries, and browser-only rendering behavior.\n\nKeep E2E coverage small and high-value:\n\n```bash\nmoonx trees:coverage\nmoonx trees:test-e2e\nmoonx path-store:test-demo\nmoonx docs:test-e2e\n```\n\nIf E2E fixtures or dev servers are started in a worktree, follow the cleanup\ncontract from the `worktrees-and-dev-servers` skill.\n",".agents/skills/tooling-and-dependencies/SKILL.md":"---\nname: tooling-and-dependencies\ndescription:\n Use when running repo scripts, adding or changing dependencies, editing\n package.json files, installing packages, publishing packages, or deciding when\n pnpm package operations versus Bun runtime commands should be invoked.\n---\n\n# Tooling and Dependencies\n\n## Toolchain (proto)\n\n- Tool versions (bun, pnpm, node, moon, gh) are pinned in `.prototools` and\n managed by [proto](https://moonrepo.dev/docs/proto); its shims put the pinned\n versions on PATH inside the repo. `proto use` installs everything after a pin\n changes.\n- Bump a tool by editing `.prototools` only — never install tools globally or\n pin versions elsewhere. moon's version is additionally enforced by\n `versionConstraint` in `.moon/workspace.yml` and mirrored as the\n `@moonrepo/cli` catalog entry (for Vercel builders without proto); keep all\n three in sync.\n- CI and local shells resolve the same toolchain: CI installs it with\n `moonrepo/setup-toolchain`, which runs `proto install` against the same\n `.prototools`.\n\n## Package Manager and Runtime\n\n- Use `pnpm` for package operations: install, add, remove, dedupe, lockfile,\n package-runner, and publish work.\n- Do not use `bun`, `npm`, `yarn`, `npx`, or other package runners for package\n operations unless there is a specific documented reason.\n- Bun remains the direct TypeScript runtime and Bun test runner where current\n moon tasks use it. Local scripts may still be `.ts` files without a separate\n compile step.\n\n## Dependency Catalog\n\nThis monorepo uses the `catalog` in `pnpm-workspace.yaml`.\n\n- Never add a version directly to an individual package's `package.json` by\n default.\n- To add a dependency:\n 1. Add the exact version to `pnpm-workspace.yaml` under `catalog`, for example\n `\"new-package\": \"1.2.3\"`.\n 2. Reference it from the package with `\"new-package\": \"catalog:\"`.\n- Do not run `pnpm add ` inside a package directory; it writes direct\n versions and breaks the catalog pattern unless you manually normalize them.\n- Published packages may intentionally use ranges for end-user compatibility.\n `apps/docs` should use catalog versions; published packages such as\n `packages/diffs` may use ranges only when that is intentional.\n\n## Tasks\n\n- All build/dev/test/lint entrypoints are moon tasks; package.json scripts exist\n only for npm lifecycle hooks (`prepublishOnly`). Never add task scripts back\n to a package.json.\n- Tasks are defined in `.moon/tasks/*.yml` (inherited) and each project's\n `moon.yml`. Repo-wide tooling (format, lint, icons, clean) lives on the `root`\n project.\n- Run tasks from anywhere in the repo:\n\n```bash\nmoon run :\nmoonx : # same engine; shorthand for moon exec\nmoonx : -- --flags # forward arguments after --\nmoon run :test # a task across every project that has it\nmoon tasks # discover a project's tasks\n```\n\n`moon run` and `moonx` (an alias binary for `moon exec`) execute the same action\npipeline: identical dependency resolution, caching, and affected support. Use\nthem interchangeably; docs write `moon run` for canonical commands and `moonx`\nin interactive examples. The one practical difference: `moonx`/`moon exec`\nexposes CI-behavior overrides (`--ignore-ci-checks`, `--ci `) that\n`moon run` lacks. `moon ci` is a third thing — the affected-aware orchestrator\nused only by `.github/workflows/ci.yml`; never reach for it locally.\n\nmoon builds dependency projects first (`deps: ['^:build']`), caches outputs, and\nskips tasks whose inputs have not changed. Local-only tasks set explicit options\ninstead of moon presets (presets force `runInCI: skip`, which moon refuses to\nrun in CI-detected shells; agent harnesses export `CI=1`):\n\n- No graph edges at all (formatters, benchmarks, wt, servers spawned by\n playwright): use `runInCI: 'always'` — runnable everywhere, and never in the\n CI pipeline because a task with no deps or dependents is never affected\n through the graph.\n- Connected to the build graph (dev/prod, e2e variants, publish guards): keep\n `runInCI: 'skip'` — `moon ci --include-relations` runs affected\n runInCI-enabled tasks even when unrequested, which would pull them into CI.\n Run them in CI-marked shells with `moonx --ignore-ci-checks` (works\n regardless of the shell's CI env). For non-moon commands that CI-gate\n themselves, unset the var instead: `CI= pnpm publish --dry-run`.\n",".agents/skills/typescript-monorepo/SKILL.md":"---\nname: typescript-monorepo\ndescription:\n Use when adding or changing packages/apps, TypeScript configs, workspace\n dependencies, package references, exports, or monorepo project-reference\n relationships.\n---\n\n# TypeScript Monorepo\n\n## TypeScript\n\nUse TypeScript everywhere practical. Compiler settings are intentionally fairly\nstrict.\n\n- Shared compiler options live in `tsconfig.options.json`.\n- Root `tsconfig.json` manages project references across the monorepo.\n- Typechecking uses TypeScript 7's native `tsc` (the successor to the `tsgo`\n preview) and runs through moon: `moonx :typecheck` (moon builds\n workspace dependencies first, since types resolve through each dependency's\n built dist). Next runs the same `tsc` for its build-time check through\n `experimental.useTypeScriptCli`, which is on by default since Next 16.3.\n\n## Project References\n\nWhen adding a new package or app:\n\n- Add it to the root `tsconfig.json` references.\n- Ensure its local `tsconfig.json` follows existing package/app patterns.\n- Give it a `moon.yml` (language, layer, tags, and any project-specific tasks);\n shared tasks come from `.moon/tasks/*.yml` via tags or project language.\n\nWhen one workspace package depends on another:\n\n- Add the dependency as `workspace:*` in the consuming package.\n- Add the dependency to the consuming package's TypeScript `references` block\n when needed for accurate and fast typechecking.\n\n## Workspace Dependencies\n\nUse the `pnpm-workspace.yaml` catalog rules from `tooling-and-dependencies` for\nexternal packages. Use `workspace:*` for internal package dependencies.\n\nIf a package is published, review its `exports`, `typesVersions`, `files`, peer\ndependencies, and its moon `prepublish` task chain before changing public\nentrypoints or dependency ranges.\n",".agents/skills/worktrees-and-dev-servers/SKILL.md":"---\nname: worktrees-and-dev-servers\ndescription:\n Use when working with the repo's moonx root:wt worktree helper, Pierre-managed\n worktrees, dev-server port offsets, stale server cleanup, Playwright fixtures,\n or Chrome debug instances. Do not use this as a substitute for host-provided\n workspace isolation.\n---\n\n# Worktrees and Dev Servers\n\nPierre includes a repo-specific `git worktree` helper for local/manual\nparallelization outside host-managed agent workspaces. Managed Pierre worktrees\nlive at:\n\n```text\n~/pierre/pierre-worktrees//\n```\n\nEach managed Pierre worktree owns a port offset so dev servers, E2E fixtures,\nand the Chrome remote-debug instance do not collide. The main clone keeps\nhistorical default ports; linked Pierre worktrees shift ports.\n\nIf you are already inside a Conductor, Codex, Claude, or other host-provided\nworkspace, do not create another worktree unless the user explicitly asks for a\nPierre-managed worktree. Still use this skill when you start repo dev servers or\nE2E fixtures, because the cleanup and port-offset rules apply to those scripts.\n\n## Worktree Commands\n\nThe `wt` suite is defined in `scripts/wt.ts`, exposed as the `root:wt` moon\ntask, and manages only Pierre-managed worktrees:\n\n```bash\nmoonx root:wt -- new # create a worktree, allocate offset, pnpm install\nmoonx root:wt -- rm # kill its processes, remove the worktree\nmoonx root:wt -- clean # kill zombie servers on all managed worktree ports\nmoonx root:wt -- clean # clean one managed worktree\nmoonx root:wt -- ps # show per-worktree port status (LISTEN / -)\nmoonx root:wt -- list # summary of managed + external worktrees\n```\n\nPort-binding moon tasks read the offset from `/.env.worktree` via\ntheir `envFile` option. Before starting, dev tasks run `scripts/run-dev.sh` to\nkill any stale process bound to the target port.\n\n## Cleanup Contract\n\nIf you start dev servers, Playwright fixtures, or Chrome debug instances inside\na worktree, run cleanup before completing your turn:\n\n```bash\nmoonx root:wt -- clean \n```\n\nUse `moonx root:wt -- clean` when you do not know the slug or need to clean\nevery managed worktree. Use `moonx root:wt -- rm ` only when intentionally\ntearing down the worktree itself.\n","AGENTS.md":"# PierreJS Monorepo\n\n## Agent Environment\n\nSet `AGENT=1` at the start of every terminal session so Bun's test runner emits\nAI-friendly output:\n\n```bash\nexport AGENT=1\n```\n\nMost local moon tasks (formatters, benchmarks, worktree management) are\nconfigured with `runInCI: 'always'` so they keep working in CI-marked shells\nlike agent harnesses. Tasks connected to the build graph (dev servers, prod\nserves, e2e variants, publish guards) stay CI-skipped — run those with\n`moonx --ignore-ci-checks`, e.g.\n`moonx docs:dev-diffs --ignore-ci-checks`. For non-moon commands that CI-gate\nthemselves, unset the var: `CI= pnpm publish --dry-run`.\n\n## Toolchain\n\n- Tool versions (bun, pnpm, node, moon, gh) are pinned in `.prototools` and\n managed by [proto](https://moonrepo.dev/docs/proto); run `proto use` if a tool\n is missing or a pin changed. Never install toolchain versions globally; bump\n pins only in `.prototools`.\n- [moon](https://moonrepo.dev/docs) is the task runner; `package.json` scripts\n are npm lifecycle hooks only.\n\n## Core Rules\n\n- Use `pnpm` for install/add/remove/dedupe/package-manager and publishing work.\n Do not use `bun`, `npm`, `yarn`, `npx`, or similar tools for package\n operations unless there is a specific reason.\n- Dependencies use the `catalog` in `pnpm-workspace.yaml`. Never add dependency\n versions directly to package-level `package.json` files unless a published\n package intentionally needs its own range.\n- Run tasks through moon: `moon run :` (or the `moonx` shorthand)\n works from anywhere in the repo. `moonx : -- args` forwards\n arguments. Discover tasks with `moon tasks `.\n- Preserve trailing newlines at the end of files.\n- Setup steps for a fresh clone live in `CONTRIBUTING.md`.\n\n## Licensing\n\nEvery package in this repo is licensed under Apache 2.0. When adding a new\npackage under `packages/*` or `apps/*`:\n\n- Set `\"license\": \"apache-2.0\"` in its `package.json`.\n- Add an Apache 2.0 `LICENSE.md` at the package root — copy one from an existing\n package (e.g. `packages/trees/LICENSE.md`).\n\nVendored third-party code keeps its original license; record that attribution in\na `NOTICE.md` next to the package rather than changing its LICENSE.\n\n`moon run root:check-licenses` enforces both requirements and runs in CI on\nevery PR.\n\n## Skills\n\nDomain-specific context and conventions live in `.agents/skills/`. Before\nstarting any task:\n\n1. List `.agents/skills/*/SKILL.md`\n2. Read only each skill's frontmatter description to identify relevant skills\n3. Read only the full `SKILL.md` files relevant to your task\n\nDo not load skills that are not relevant to the task.\n\n## Agent Artifacts\n\nWrite agent-only planning and scratch artifacts under `.agents/ignore/` by\ndefault:\n\n- Plans: `.agents/ignore/plans/YYYY-MM-DD-.md`\n- Specs: `.agents/ignore/specs/YYYY-MM-DD-.md`\n\n`.agents/ignore/` is gitignored. Do not put source files, tests, or committed\ndocumentation there.\n\n## Verification Baseline\n\nAfter code changes, verification is not complete until you have run these from\nanywhere in the repo:\n\n```bash\nmoon run root:format root:lint\n```\n\nAlso run the affected typecheck and focused tests for the changed area, e.g.\n`moonx :typecheck` and `moonx :test` (or\n`moonx :typecheck --affected`). For docs-only or AGENTS/skill-only changes,\nformatting and linting are sufficient unless the edit touches executable code or\npackage config.\n\n## Code Readability\n\n- When adding non-trivial helpers, prefer a short comment directly above the\n function explaining what the helper does and why it exists.\n- Write comments for readers new to the codepath. Avoid vague shorthand like\n \"snapshot\" unless you immediately explain what data is captured or derived.\n- Prefer function-level comments over many inline comments. Use inline comments\n only when a specific step is still non-obvious.\n- Keep comments concrete and behavior-focused.\n","CLAUDE.md":"@AGENTS.md\n","packages/diffs/README.md":"","packages/diffs/test/README.md":"","packages/highlights/README.md":"","packages/highlights/benchmark/README.md":"","packages/highlights/themes/README.md":"","packages/path-store/README.md":"","packages/pipes/README.md":"","packages/theme/README.md":"","packages/theme/zed/README.md":"","packages/theming/README.md":"","packages/trees/README.md":"","skills/INDEX.md":"# Pierre package skills\n\nUse these skills when an app or site consumes a Pierre package. Read the\nselected `SKILL.md` first. Load only the API or recipe reference that matches\nthe task.\n\n| Skill | Use it for |\n| --------------------------------- | --------------------------------------------------------------------------------------------------- |\n| [diffs](diffs/SKILL.md) | Render or edit code files, diffs, patches, and merge conflicts with `@pierre/diffs`. |\n| [highlights](highlights/SKILL.md) | Generate HTML or themed tokens, stream code, and apply incremental edits with `@pierre/highlights`. |\n| [theme](theme/SKILL.md) | Select and load a Pierre syntax or editor theme from `@pierre/theme`. |\n| [theming](theming/SKILL.md) | Build runtime theme collections, resolvers, controllers, and color mappings with `@pierre/theming`. |\n| [trees](trees/SKILL.md) | Render and control an interactive file tree with `@pierre/trees`. |\n\n## Package relationship\n\n`@pierre/theme` supplies theme objects. `@pierre/theming` selects, resolves, and\nmaps those objects. `@pierre/diffs` and `@pierre/trees` render code and file\ntrees with the selected theme.\n\n`@pierre/highlights` generates standalone HTML or tokens using Zed-compatible\nthemes from `@pierre/highlights/themes`. Its theme objects use a different\nformat from the Shiki and VS Code themes in `@pierre/theme`.\n","skills/diffs/SKILL.md":"---\nname: diffs\ndescription:\n Use when an app uses @pierre/diffs to render or edit code files, diffs,\n patches, merge conflicts, or CodeView review surfaces, including React,\n vanilla JavaScript, SSR, workers, annotations, selection, and custom syntax\n languages or themes.\n---\n\n# `@pierre/diffs`\n\nUse `@pierre/diffs` to render syntax-highlighted files and diffs. Use its\noptional editor, SSR, and worker entries for those capabilities.\n\nFor standalone HTML or token generation with `@pierre/highlights`, read the\n[highlights skill](../highlights/SKILL.md).\n\n## Install\n\n```bash\npnpm add @pierre/diffs\n```\n\nInstall `react` and `react-dom` when the app uses the React entry.\n\n## Select an API reference\n\n| Surface | Reference |\n| ------------------------------------------------------------ | ------------------------------------------------------ |\n| Root components, parsing, and file extension APIs | [Core API](references/api-core.md) |\n| Languages, themes, highlighter state, and streams | [Highlighting API](references/api-highlighting.md) |\n| Renderers, managers, DOM helpers, comparisons, and constants | [Low-level rendering API](references/api-rendering.md) |\n| Shared data, option, render, selection, and editor types | [Shared types](references/api-types.md) |\n| `@pierre/diffs/react` | [React API](references/api-react.md) |\n| `@pierre/diffs/edit` | [Editor API](references/api-editor.md) |\n| `@pierre/diffs/ssr` | [SSR API](references/api-ssr.md) |\n| `@pierre/diffs/worker` and worker scripts | [Worker API](references/api-worker.md) |\n\n## Select a recipe\n\n| Task | Recipe |\n| ----------------------------------- | ------------------------------------------------------------------------ |\n| Render a file or diff in React | [Render with React](references/recipe-react.md) |\n| Render a file or diff without React | [Render with vanilla JavaScript](references/recipe-vanilla.md) |\n| Build a virtualized review surface | [Use CodeView](references/recipe-code-view.md) |\n| Edit a React surface or CodeView | [Edit with React](references/recipe-edit-react.md) |\n| Edit a vanilla surface or CodeView | [Edit with vanilla JavaScript](references/recipe-edit-vanilla.md) |\n| Preload markup on the server | [Use SSR](references/recipe-ssr.md) |\n| Highlight through a worker pool | [Use workers](references/recipe-workers.md) |\n| Add line annotations and selection | [Add annotations and selection](references/recipe-annotations.md) |\n| Register a custom language or theme | [Register custom highlighting](references/recipe-custom-highlighting.md) |\n","skills/diffs/references/api-core.md":"# Core API\n\nThis reference covers components, parsing, merge conflicts, and file extension\nAPIs from `@pierre/diffs`.\n\n## Contents\n\n- [File components](#file-components)\n- [Virtualized components](#virtualized-components)\n- [`File` members](#file-members)\n- [`FileDiff` members](#filediff-members)\n- [`CodeView` members](#codeview-members)\n- [Parsing and patch APIs](#parsing-and-patch-apis)\n- [Merge conflict APIs](#merge-conflict-apis)\n- [Annotation APIs](#annotation-apis)\n- [File extension APIs](#file-extension-apis)\n\n## File components\n\n| Export | Kind | Purpose |\n| --------------------------------------- | -------- | ------------------------------------------------------------- |\n| `File` | Class | Renders one syntax-highlighted file. |\n| `FileOptions` | Type | Configures file display, interaction, slots, and callbacks. |\n| `FileRenderProps` | Type | Defines file input and a render target. |\n| `FileHydrateProps` | Type | Defines file input and preloaded markup for hydration. |\n| `FileDiff` | Class | Renders a file diff from files or parsed metadata. |\n| `FileDiffOptions` | Type | Configures diff display, interaction, slots, and callbacks. |\n| `FileDiffRenderBaseProps` | Type | Defines shared diff render input. |\n| `FileDiffRenderProps` | Type | Adds files or parsed metadata to diff render input. |\n| `FileDiffHydrationProps` | Type | Defines diff input and preloaded markup for hydration. |\n| `FileDiffType` | Type | Identifies a standard or unresolved diff instance. |\n| `UnresolvedFile` | Class | Renders one file with merge conflict controls. |\n| `UnresolvedFileOptions` | Type | Configures merge conflict display and callbacks. |\n| `UnresolvedFileRenderProps` | Type | Defines merge conflict render input. |\n| `UnresolvedFileHydrationProps` | Type | Defines merge conflict input for hydration. |\n| `MergeConflictActionsTypeOption` | Type | Selects no actions, default actions, or a custom renderer. |\n| `RenderMergeConflictActions` | Type | Defines a vanilla conflict action renderer. |\n| `getUnresolvedDiffHunksRendererOptions` | Function | Converts unresolved-file options to hunk renderer options. |\n| `CodeView` | Class | Renders a virtualized list of files and diffs. |\n| `CodeViewOptions` | Type | Configures list layout, items, slots, selection, and editing. |\n| `CodeViewLineSelection` | Type | Associates a selected range with one item ID. |\n| `CodeViewRenderedFileItem` | Type | Describes one mounted file item. |\n| `CodeViewRenderedDiffItem` | Type | Describes one mounted diff item. |\n| `CodeViewRenderedItem` | Type | Represents a mounted file or diff item. |\n| `CodeViewCoordinator` | Type | Coordinates React slots with the vanilla list. |\n| `CodeViewSlotSnapshot` | Type | Describes mounted items and list header or footer hosts. |\n| `CodeViewScrollListener` | Type | Receives list scroll changes. |\n| `CODE_VIEW_FILE_OPTION_KEYS` | Value | Lists file options that `CodeView` passes to an item. |\n| `CODE_VIEW_DIFF_OPTION_KEYS` | Value | Lists diff options that `CodeView` passes to an item. |\n\n## Virtualized components\n\n| Export | Kind | Purpose |\n| -------------------------------------------------- | ----- | ----------------------------------------------------------- |\n| `Virtualizer` | Class | Tracks a simple viewport and connected render instances. |\n| `VirtualizerConfig` | Type | Configures overscroll, observation margin, and resize logs. |\n| `VirtualizedFile` | Class | Adds simple viewport behavior to `File`. |\n| `VirtualizedFileDiff` | Class | Adds simple viewport behavior to `FileDiff`. |\n| `VIRTUALIZED_FILE_DIFF_LAYOUT_CHECKPOINT_INTERVAL` | Value | Sets the line interval for virtual diff layout checkpoints. |\n\n## `File` members\n\n| Member | Purpose |\n| --------------------------------------------- | ---------------------------------------------------- |\n| `new File(options?, workerManager?)` | Creates one file renderer. |\n| `render(props)` | Renders file contents. |\n| `hydrate(props)` | Attaches to preloaded file markup. |\n| `rerender()` | Renders the current file again. |\n| `setOptions(options)` | Replaces file options. |\n| `setThemeType(themeType)` | Selects system, light, or dark theme mode. |\n| `onThemeChange()` | Applies a changed theme. |\n| `setLineAnnotations(annotations)` | Replaces file annotations. |\n| `setSelectedLines(range, options?)` | Replaces the selected line range. |\n| `setEditorActiveLine(line, options?)` | Marks the editor's active line. |\n| `getHoveredLine()` | Gets the current hovered line. |\n| `getOrCreateLineCache(file?)` | Gets cached source lines. |\n| `attachEditor(editor)` | Attaches an editor and returns a detach function. |\n| `applyDocumentChange(document, annotations?)` | Applies an editor document update. |\n| `updateRenderCache(tokens, themeType)` | Updates highlighted token cache entries. |\n| `primeHighlightCache()` | Preloads the highlighted file result. |\n| `renderPlaceholder(height)` | Renders a fixed-height placeholder. |\n| `virtualizedSetup()` | Prepares the instance for a virtualizer. |\n| `flushManagers()` | Applies deferred interaction and size manager state. |\n| `cleanUp(recycle?)` | Releases rendered resources. |\n\n## `FileDiff` members\n\n`FileDiff` supports the shared `File` update, selection, annotation, editor,\nhydration, placeholder, and cleanup members with diff data.\n\n| Member | Purpose |\n| -------------------------------------------- | ------------------------------------------------ |\n| `new FileDiff(options?, workerManager?)` | Creates one diff renderer. |\n| `render(props)` | Parses or renders diff input. |\n| `hydrate(props)` | Attaches to preloaded diff markup. |\n| `rerender()` | Renders the current diff again. |\n| `setOptions(options)` | Replaces diff options. |\n| `getLineIndex(line, side?)` | Maps a displayed line to row and column indexes. |\n| `handleExpandHunk(index, direction, count?)` | Handles a hunk expansion request. |\n| `expandHunk(index, direction, count?)` | Expands hidden context around one hunk. |\n| `completeEditSession()` | Recomputes diff metadata after an edit session. |\n| `isLineRenderable(line)` | Tests whether an additions line is visible. |\n| `getNearestRenderableLine(line, direction)` | Finds a visible additions line. |\n| `revealLine(line)` | Expands context to show an additions line. |\n| `primeHighlightCache(diff?)` | Preloads the highlighted diff result. |\n\n## `CodeView` members\n\n| Member | Purpose |\n| ---------------------------------------- | -------------------------------------------- |\n| `new CodeView(options?, workerManager?)` | Creates one virtualized list. |\n| `setup(root)` | Attaches the list to its scroll root. |\n| `setItems(items)` | Replaces all items. |\n| `addItem(item)` | Appends one item. |\n| `addItems(items)` | Appends several items. |\n| `getItem(id)` | Gets one item by ID. |\n| `updateItem(item)` | Replaces one item by ID. |\n| `updateItemId(oldId, newId)` | Changes one item ID. |\n| `getEditor(id)` | Gets the active editor for an item. |\n| `scrollTo(target)` | Scrolls to a position, item, line, or range. |\n| `setSelectedLines(selection, options?)` | Sets the selected item and range. |\n| `getSelectedLines()` | Gets the selected item and range. |\n| `clearSelectedLines(options?)` | Clears the selected lines. |\n| `setOptions(options)` | Replaces list options. |\n| `onThemeChange()` | Applies a changed theme to list items. |\n| `render(immediate?)` | Schedules or performs a render. |\n| `getWindowSpecs()` | Gets the current virtual window. |\n| `getContainerElement()` | Gets the scroll content element. |\n| `getHeaderElement()` | Gets the list header host. |\n| `getFooterElement()` | Gets the list footer host. |\n| `getRenderedItems()` | Gets mounted items. |\n| `setSlotCoordinator(coordinator?)` | Sets the external slot coordinator. |\n| `getSlotSnapshot(coordinator)` | Gets the coordinator's mounted slot state. |\n| `subscribeToScroll(listener)` | Subscribes to scroll changes. |\n| `getLocalTopForInstance(instance)` | Gets an instance offset inside the list. |\n| `getTopForItem(id)` | Gets an item offset inside the list. |\n| `instanceChanged(instance, layoutDirty)` | Reports a render instance change. |\n| `reset()` | Clears items and render state. |\n| `cleanUp()` | Releases list resources. |\n\n## Parsing and patch APIs\n\n| Export | Purpose |\n| ---------------------------- | ----------------------------------------------------- |\n| `parseDiffFromFile` | Creates `FileDiffMetadata` from old and new files. |\n| `parsePatchFiles` | Parses a patch string into file diff metadata. |\n| `processPatch` | Parses one patch section. |\n| `processFile` | Converts one parsed patch file to `FileDiffMetadata`. |\n| `getSingularPatch` | Selects one file patch from a patch string. |\n| `trimPatchContext` | Limits unchanged context in patch text. |\n| `hydratePartialDiff` | Adds loaded file contents to partial diff metadata. |\n| `cloneFileDiffMetadata` | Creates a structural copy of diff metadata. |\n| `cleanLastNewline` | Normalizes the final newline for diff input. |\n| `getLineEndingType` | Detects a file's line-ending sequence. |\n| `getTotalLineCountFromHunks` | Counts rendered rows across hunks. |\n| `parseLineType` | Parses one patch line marker and content. |\n| `ParsedLine` | Describes the result from `parseLineType`. |\n\n## Merge conflict APIs\n\n| Export | Purpose |\n| ---------------------- | --------------------------------------------------------------- |\n| `resolveConflict` | Applies one current, incoming, or combined conflict resolution. |\n| `resolveRegion` | Resolves one parsed merge conflict region. |\n| `diffAcceptRejectHunk` | Applies accept or reject behavior to one change hunk. |\n\n## Annotation APIs\n\n| Export | Purpose |\n| ---------------------------- | ---------------------------------------------------------- |\n| `isFileAnnotation` | Tests whether one annotation targets a file line. |\n| `isDiffAnnotation` | Tests whether one annotation targets a diff side and line. |\n| `isFileAnnotationCollection` | Tests whether an array contains file annotations. |\n| `isDiffAnnotationCollection` | Tests whether an array contains diff annotations. |\n\n## File extension APIs\n\n| Export | Purpose |\n| ---------------------------- | ------------------------------------------------ |\n| `getFiletypeFromFileName` | Infers a language from a file name. |\n| `setCustomExtension` | Maps one file name or extension to a language. |\n| `replaceCustomExtensions` | Replaces all custom mappings. |\n| `getCustomExtensionsMap` | Gets a copy of custom mappings. |\n| `getCustomExtensionsVersion` | Gets the mapping revision. |\n| `EXTENSION_TO_FILE_FORMAT` | Maps built-in extensions and names to languages. |\n| `setLanguageOverride` | Assigns a language to parsed diff files. |\n","skills/diffs/references/api-editor.md":"# Editor API\n\nThis reference lists the primary exports from `@pierre/diffs/edit` and the\neditor APIs used by common integrations.\n\n## Exports\n\n| Export | Kind | Purpose |\n| --------------------------- | ----- | -------------------------------------------------------------- |\n| `CaretMetadata` | Type | Supplies the color shared by a remote caret and its highlight. |\n| `Editor` | Class | Adds text editing to a `File` or `FileDiff` instance. |\n| `EditorCaret` | Type | Describes an externally owned caret or highlighted selection. |\n| `EditStateManager` | Value | Manages keyed in-memory edit history and state. |\n| `ClearEditStateOptions` | Type | Selects retained state parts to clear. |\n| `EditState` | Type | Holds one complete live editing session. |\n| `EditorInitialState` | Type | Selects state fields to supply on first attachment. |\n| `EditorChange` | Type | Describes one normalized editor change. |\n| `EditorChangeEvent` | Type | Provides normalized edits and the current document. |\n| `EditorActiveLineOptions` | Type | Configures reveal behavior for an editor active line. |\n| `EditorEditCompleteEvent` | Type | Unites file and diff completion events for editor observation. |\n| `FileEditCompleteEvent` | Type | Describes a completed file edit session. |\n| `FileDiffEditCompleteEvent` | Type | Describes a completed diff edit session. |\n| `EditorCommand` | Type | Names an editor command. |\n| `EditorType` | Type | Selects a `file` or `file-diff` editor surface. |\n| `EditorFactory` | Type | Defines an editor-type-aware editor factory. |\n| `EditorFocusOptions` | Type | Selects a focus target and scroll behavior. |\n| `EditorKeymap` | Type | Defines ordered custom shortcut groups. |\n| `EditorOptions` | Type | Configures history, initial state, behavior, and events. |\n| `EditorShortcut` | Type | Defines one command shortcut. |\n| `EditorSelection` | Type | Adds caret direction to an editor range. |\n| `EditorViewState` | Type | Holds selections and editor-owned viewport offsets. |\n| `EditorViewportState` | Type | Holds horizontal and optional vertical scroll offsets. |\n| `KeyboardKey` | Type | Names a key accepted by an editor shortcut. |\n| `KeyboardModifier` | Type | Names a modifier accepted by an editor shortcut. |\n| `TextDocument` | Class | Stores text, positions, edits, search, and undo history. |\n| `TextDocumentChange` | Type | Describes the lines and characters changed by an edit. |\n| `Position` | Type | Identifies a zero-based line and character. |\n| `Range` | Type | Identifies a start and end position. |\n| `ResolvedTextEdit` | Type | Stores an edit with resolved document offsets. |\n| `SelectionDirection` | Type | Selects backward, neutral, or forward selection direction. |\n| `TextEdit` | Type | Replaces one range with new text. |\n| `Marker` | Type | Describes an editor diagnostic marker. |\n| `MarkerSeverity` | Type | Selects an editor marker severity. |\n\n## Lower-level exports\n\nThe edit entrypoint also exposes the state-management, keyboard-resolution,\nmarker-rendering, and popover-placement building blocks used by `Editor`.\n\n| Export | Kind | Purpose |\n| --------------------------------------- | -------- | --------------------------------------------------------------------- |\n| `ManagedEditSession` | Type | Selects mutable in-progress editor state by editor type. |\n| `ManagedFileEditSession` | Type | Holds mutable state for an active file editor session. |\n| `ManagedFileDiffEditSession` | Type | Holds mutable state for an active file-diff editor session. |\n| `cloneEditorViewState` | Function | Clones editor selections and viewport state. |\n| `toManagedEditState` | Function | Returns complete edit state when a managed session has required data. |\n| `resolveEditorCommandFromKeyboardEvent` | Function | Resolves a keyboard event through custom and default editor keymaps. |\n| `resolveFindAgainShortcut` | Function | Recognizes the next or previous native find shortcut. |\n| `MarkerRenderOptions` | Type | Supplies marker rendering, measurement, and popover dependencies. |\n| `MarkerRenderer` | Class | Renders marker ranges and marker hover popovers. |\n| `markerSeverityDatasetKey` | Function | Maps a marker severity to its DOM dataset key. |\n| `POPOVER_BOUNDARY_LINES` | Value | Sets the document-edge fallback threshold for popover placement. |\n| `POPOVER_FLIP_HYSTERESIS_PX` | Value | Sets the clearance required before a flipped popover returns. |\n| `PopoverPlacementBounds` | Type | Describes vertical popover placement bounds. |\n| `PopoverViewportBounds` | Type | Describes all visible viewport edges for popover clamping. |\n| `PopoverManagerOptions` | Type | Supplies active-popover state callbacks to `PopoverManager`. |\n| `PopoverManager` | Class | Tracks viewport geometry and stable popover placement. |\n| `setPopoverPositionStyles` | Function | Writes the CSS properties used to position and clamp a popover. |\n\n## `EditorOptions` fields\n\n| Field | Purpose |\n| ------------------------ | -------------------------------------------------------- |\n| `historyMaxEntries` | Limits the undo stack. |\n| `ownsVerticalViewport` | Opts into vertical scroll retention at construction. |\n| `initialState` | Supplies partial or complete state on first attach. |\n| `keymap` | Adds shortcut groups checked before the defaults. |\n| `roundedSelection` | Controls rounded selection corners. |\n| `matchBrackets` | Controls matching-bracket highlights. |\n| `autoSurround` | Controls quote and bracket insertion around a selection. |\n| `languageCommentConfig` | Overrides comment tokens by language. |\n| `enabledSelectionAction` | Enables the selection action surface. |\n| `clipboard` | Supplies a text clipboard reader. |\n| `renderSelectionAction` | Produces the selection action element. |\n| `renderCaret` | Produces an externally owned caret element. |\n| `onAttach` | Receives the editor and attached surface. |\n| `onChange` | Receives the event, including its editor instance. |\n| `onComplete` | Observes the completed file or diff event. |\n| `onFocus` | Runs after the editor gains focus. |\n| `onBlur` | Runs after the editor loses focus. |\n\nFor a `file-diff` editor, view-only `initialState` can omit document and diff\nmetadata. Transferring an edited document and its undo/redo history requires the\nmatching `document`, `fileInfo`, and `diffSession` from one complete\n`EditState`.\n\n`onComplete` receives the exact frozen event that is also passed to the\ncomponent's `onEditComplete` or CodeView's `onItemEditComplete`. The editor\nobserver runs first and still runs when the component callback is missing. You\ncannot accept or reject from this API. It is here for symmetry, but most\nintegrations should use those component callbacks instead.\n\nUse `editStateKey` for ordinary same-runtime restoration. It retains the draft,\nundo/redo history, selections, horizontal code scroll, eligible vertical scroll,\nand FileDiff resume metadata without an application synchronization loop. It is\nbounded in-memory state and does not survive a reload.\n\nUse `getViewState()` and `setViewState()` for an isolated selection/view copy or\ndurable application persistence. An attached surface reports horizontal\n`scrollLeft`. It reports `scrollTop` only when `ownsVerticalViewport: true` was\npassed to the constructor and the surface exclusively owns an element viewport.\nVirtualization alone does not imply ownership; page, ancestor, and CodeView\nshared scrolling remain application/viewer state.\n\n`getEditState()` exposes the raw objects from the latest complete edit-lifecycle\ncheckpoint. Checkpoints run after synchronization, document edits, explicit\n`setViewState()` calls, recycling, and completion. Selection or scroll movement\nalone does not update it; use `getViewState()` for an exact live copy. State\nremains available while rendering is recycled and during `onComplete`, and\nreturns `undefined` before synchronization or after completion. The result is\nborrowed editor-owned state rather than a serialization format.\n\n## `Editor` members\n\n| Member | Purpose |\n| -------------------------------------------------------- | ------------------------------------------------------- |\n| `new Editor(type, options?, editStateKey?)` | Creates an editor with optional keyed state retention. |\n| `type` | Identifies the editor as `file` or `file-diff`. |\n| `edit(instance)` | Attaches and returns the normal completion disposer. |\n| `setOptions(options)` | Merges editor options. |\n| `applyEdits(edits, updateHistory?)` | Applies programmatic text edits. |\n| `canUndo` | Reports whether undo has an entry. |\n| `canRedo` | Reports whether redo has an entry. |\n| `undo()` | Reverts the latest edit. |\n| `redo()` | Reapplies the latest reverted edit. |\n| `getFile()` | Gets the current file contents. |\n| `getText()` | Gets the current text. |\n| `getViewState()` | Gets selections and editor-owned view state. |\n| `setViewState(state)` | Sets selections and editor-owned view state. |\n| `getEditState()` | Gets the latest edit-lifecycle state checkpoint. |\n| `setSelections(selections)` | Sets directed selection ranges. |\n| `setCarets(carets)` | Replaces the externally owned caret and highlight list. |\n| `setMarkers(markers)` | Sets diagnostic markers. |\n| `focus(options?)` | Focuses the editor. |\n| `blur()` | Removes editor focus. |\n| `cleanUp(reason?: 'discard' \\| 'recycle' \\| 'complete')` | Suspends rendering or completes the editing session. |\n\n`editStateKey` opts an editor into retained in-memory sessions across editor\ninstances. File and file-diff namespaces are independent and each keeps up to\n100 inactive entries by default. The same type/key cannot be active in two\neditors at once.\n\nCall the disposer returned by `edit(instance)` for the normal session-ending\npath; it is equivalent to `cleanUp('complete')` and installs an accepted\ncompletion result. `cleanUp('discard')` still publishes the completion event but\ndoes not install its result. `cleanUp('recycle')` suspends rendering without\nending the session or changing the editor-component association. Calling\n`edit(instance)` again resumes rendering for that same component.\n\n## `EditStateManager` members\n\n| Member | Purpose |\n| ----------------------------------- | --------------------------------------------------------------- |\n| `get(type, editStateKey)` | Borrows active or inactive complete state without touching LRU. |\n| `clear(type, editStateKey, parts?)` | Clears inactive complete or granular state. |\n| `clearAll()` | Clears all inactive state without mutating active editors. |\n| `setCapacity(capacity)` | Sets each namespace's inactive retained-state capacity. |\n\n`clear()` returns `false` for active or missing state. Omit `parts` to remove\nthe complete entry. `{ document: true }` also removes the complete entry because\nall other parts depend on it. Use `{ history: true }`, `{ selections: true }`,\n`{ view: true }`, or `{ editor: true }` to keep the document while clearing undo\nhistory, cursor state, scroll state, or both view-state parts respectively.\n\nFor durable persistence, store `FileContents` and optional JSON-safe\n`EditorViewState` separately, then construct a fresh `TextDocument` when\nrestoring. Complete `EditState` and undo/redo history are not serialization\ncontracts.\n\n## `TextDocument` members\n\n| Member | Purpose |\n| ---------------------------------------------------- | ----------------------------------------------------- |\n| `new TextDocument(uri, text, languageId?, version?)` | Creates a text document. |\n| `uri` | Gets the document identifier. |\n| `languageId` | Gets the language identifier. |\n| `version` | Gets the document version. |\n| `lineCount` | Gets the line count. |\n| `eol` | Gets the line-ending sequence. |\n| `canUndo` | Reports whether undo has an entry. |\n| `canRedo` | Reports whether redo has an entry. |\n| `positionAt(offset)` | Converts an offset to a position. |\n| `positionsAt(offsets)` | Converts several offsets to positions. |\n| `offsetAt(position)` | Converts a position to an offset. |\n| `getText(range?)` | Gets all text or one range. |\n| `getLineText(line, includeLineBreak?)` | Gets one line. |\n| `normalizeEol(text)` | Converts text to the document line ending. |\n| `getLineLength(line, includeLineBreak?)` | Gets one line length. |\n| `charAt(offsetOrPosition)` | Gets one character. |\n| `getTextSlice(start, end)` | Gets text between two offsets. |\n| `findNextNonOverlappingSubstring(needle, occupied)` | Finds an unused substring range. |\n| `search(params)` | Finds text ranges. |\n| `applyEdits(edits, ...)` | Resolves and applies position-based edits. |\n| `resolveEdits(edits)` | Converts position-based edits to offset edits. |\n| `applyResolvedEdits(edits, ...)` | Applies offset-based edits. |\n| `setLastUndoSelectionsAfter(selections)` | Associates selections with the latest history entry. |\n| `setLastUndoLineAnnotations(before, after)` | Associates annotations with the latest history entry. |\n| `undo()` | Reverts one document history entry. |\n| `redo()` | Reapplies one document history entry. |\n| `normalizePosition(position)` | Clamps a position to the document. |\n","skills/diffs/references/api-highlighting.md":"# Highlighting API\n\n`preferredHighlighter` selects `'shiki-js'` (default), `'shiki-wasm'`, or\n`'highlights'`. Backends load lazily. File, FileDiff, Editor, FileStream, SSR\npreload options, and worker highlighter options accept this selection.\n\nOnly one backend type can be loaded per JavaScript realm (page, worker, or SSR\nprocess). Requests without `preferredHighlighter` use the loaded type, else\n`'shiki-js'`. Shared-highlighter requests (components, `getSharedHighlighter`,\n`preloadHighlighter`) keep using the loaded type even when they name another\none; they do not throw. `createHighlighter` with another type throws. To switch\ntypes, dispose every instance of the loaded type, shared or from\n`createHighlighter`. `getHighlighterType()` returns the loaded type.\n\n## Shared highlighter\n\n```ts\nimport { getSharedHighlighter } from '@pierre/diffs';\n\nconst highlighter = await getSharedHighlighter({\n preferredHighlighter: 'highlights',\n themes: ['pierre-dark'],\n langs: ['typescript'],\n});\nconst html = highlighter.codeToHtml('const value = 1;', {\n lang: 'typescript',\n theme: 'pierre-dark',\n});\n```\n\n`DiffsHighlighter` is an abstract class with `name`, `themeResolver`,\n`getTheme`, `codeToHtml`, `codeToTokens`, `createEditorTokenizer`,\n`createStreamTokenizer`, `loadLanguages`, `hasLoadedLanguages`,\n`attachLanguages`, and `dispose`. Highlights bundles its lexers, so its language\nmethods do nothing and `hasLoadedLanguages` is true until disposal. Import\nbackend-specific Shiki APIs and types from `shiki` directly.\n\n| Export | Purpose |\n| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |\n| `getSharedHighlighter` | Gets or creates the shared instance and loads themes/languages. |\n| `createHighlighter` | Creates an independently disposable instance: `createHighlighter('highlights')`. |\n| `getHighlighterType` | Returns the backend type loaded in this realm, if any. |\n| `preloadHighlighter` | Loads the same settings before a render. |\n| `getHighlighterIfLoaded` | Gets the loaded shared instance when its requested settings are available. |\n| `isHighlighterLoaded`, `isHighlighterLoading`, `isHighlighterNull` | Inspect shared state without arguments. Use `getHighlighterIfLoaded()` to obtain a ready instance. |\n| `disposeHighlighter` | Disposes the shared instance and clears resolved caches; retained `createHighlighter` instances keep their themes. |\n| `getHighlighterOptions` | Converts component options to highlighter input. |\n| `getHighlighterThemeStyles` | Creates component CSS from a loaded theme. |\n| `getThemes` | Converts a theme name or light/dark pair to a name list. |\n\n## Themes\n\n`DiffsTheme` contains `name`, `type`, `fg`, `bg`, optional editor `colors`, and\nbackend syntax data: `textmate` for Shiki and `zed` for Highlights. Bundled\nPierre and Shiki theme names also resolve to bundled Highlights palettes.\n\n| Export | Purpose |\n| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |\n| `registerCustomTheme(name, loader, type = 'textmate')` | Registers a loader with type `'textmate'` for Shiki, `'zed'` for Highlights, or `'diffs'` for portable themes. |\n| `createCSSVariablesTheme` | Creates a portable palette; accepts name, variablePrefix (default `--diffs-`), variableDefaults, and fontStyle. |\n| `registerCustomCSSVariableTheme` | Preserves `(name, variableDefaults, fontStyle = false)` and the `--diffs-` prefix. |\n| `resolveTheme`, `resolveThemes` | Resolve themes; optional second argument selects the backend. |\n| `getResolvedOrResolveTheme`, `getResolvedThemes`, `hasResolvedThemes` | Read or populate the selected backend's cache. |\n| `attachResolvedThemes` | Seeds resolved themes into a highlighter, including worker instances. |\n| `areThemesAttached` | Checks cached themes; optionally takes a backend name or highlighter. |\n| `cleanUpResolvedThemes` | Clears caches, preserving registrations. |\n\n`createCSSVariablesTheme` previously re-exported Shiki's\n`createCssVariablesTheme`, whose default prefix is `--shiki-` and whose result\nis a raw Shiki registration. Pass `variablePrefix: '--shiki-'` to keep\nstylesheets written for that default, or import Shiki's helper directly when a\nraw registration is needed.\n\nLoaders return a theme directly or as a module's `default` export. Register one\nloader per name and type; explicit TextMate or Zed loaders take priority over a\nshared Diffs loader. TextMate and Diffs names must match the registration. Zed\nthemes use the registered name instead of their display name; a `ThemeFamily`\nuses its first member unless the loader selects another.\n\nResolve themes on the main thread before passing them to workers. For one theme\nacross backends, use `createCSSVariablesTheme` or a `DiffsTheme` containing both\n`textmate` (Shiki's normalized `ThemeRegistrationResolved`) and `zed` palettes.\n\n## Languages\n\n`registerCustomLanguage(name, loader, extensions?)` registers TextMate grammars\nfor Shiki. Highlights includes its supported lexers and ignores custom grammar\nregistrations. Explicit unknown languages fall back to plain text in Highlights.\n\n`resolveLanguage(s)`, `getResolvedLanguages`, `hasResolvedLanguages`,\n`getResolvedOrResolveLanguage`, `attachResolvedLanguages`,\n`areLanguagesAttached`, and `cleanUpResolvedLanguages` support Shiki grammar\nloading. Language loader/cache maps remain available for compatibility.\n\n## Rendering and streams\n\n`renderFileWithHighlighter` and `renderDiffWithHighlighter` create component\nsyntax trees from backend-independent tokens.\n\nUse `highlighter.createStreamTokenizer(options)` for incremental append-only\ninput and `highlighter.createEditorTokenizer(options)` for document editing.\n`FileStream` connects a readable code stream through `setup(source, wrapper)`,\naccepts `preferredHighlighter`, supports `setThemeType`, and releases its stream\nthrough `cleanUp()`.\n","skills/diffs/references/api-react.md":"# React API\n\nThis reference lists the React-specific exports from `@pierre/diffs/react`. The\nentry also re-exports every type in [Shared types](api-types.md).\n\n## Components and hooks\n\n| Export | Kind | Purpose |\n| --------------------------- | --------- | --------------------------------------------------------- |\n| `File` | Component | Renders one code file. |\n| `FileDiff` | Component | Renders pre-parsed diff metadata. |\n| `MultiFileDiff` | Component | Parses and renders an old and new file pair. |\n| `PatchDiff` | Component | Parses and renders one unified patch string. |\n| `UnresolvedFile` | Component | Renders and resolves merge conflicts in one file. |\n| `CodeView` | Component | Renders a virtualized list of files and diffs. |\n| `Virtualizer` | Component | Provides simple viewport virtualization. |\n| `useVirtualizer` | Hook | Gets the nearest simple `Virtualizer` instance. |\n| `EditProvider` | Component | Supplies an editor factory. |\n| `useCreateEditor` | Hook | Gets the nearest editor factory. |\n| `WorkerPoolContextProvider` | Component | Creates and supplies a worker pool. |\n| `useWorkerPool` | Hook | Gets the nearest worker pool. |\n| `useFileInstance` | Hook | Creates and manages a vanilla `File` instance. |\n| `useFileDiffInstance` | Hook | Creates and manages a vanilla `FileDiff` instance. |\n| `useStableCallback` | Hook | Returns a stable callback that reads the latest function. |\n\n## Component and provider types\n\n| Export | Purpose |\n| ----------------------------------- | ----------------------------------------------------------------- |\n| `FileProps` | Defines props for `File`. |\n| `FileOptions` | Defines vanilla file options and the React `options` prop. |\n| `FileDiffProps` | Defines props for `FileDiff`. |\n| `MultiFileDiffProps` | Defines props for `MultiFileDiff`. |\n| `PatchDiffProps` | Defines props for `PatchDiff`. |\n| `UnresolvedFileProps` | Defines props for `UnresolvedFile`. |\n| `UnresolvedFileReactOptions` | Defines merge-conflict options for React. |\n| `DiffBasePropsReact` | Defines props shared by React diff components. |\n| `CodeViewProps` | Defines controlled or uncontrolled `CodeView` props. |\n| `ControlledCodeViewProps` | Defines `CodeView` props with `items`. |\n| `UncontrolledCodeViewProps` | Defines `CodeView` props with `initialItems`. |\n| `CodeViewReactOptions` | Defines the React-safe `CodeView` option set. |\n| `CodeViewHandle` | Defines imperative list, selection, scroll, and editor controls. |\n| `EditorFactory` | Re-exports the editor factory type from `@pierre/diffs/edit`. |\n| `EditProviderProps` | Defines the type-aware `EditProvider` factory prop. |\n| `MergeConflictActionsTypeOption` | Selects no actions, default actions, or a custom action renderer. |\n| `RenderMergeConflictActionContext` | Supplies conflict resolution to a custom action renderer. |\n| `RenderMergeConflictActions` | Defines a custom conflict action renderer. |\n| `WorkerInitializationRenderOptions` | Defines initial worker languages and render options. |\n| `WorkerPoolOptions` | Defines the worker factory, pool size, and cache size. |\n\n## Contexts and render helpers\n\n| Export | Kind | Purpose |\n| ------------------------- | -------- | ------------------------------------------------------ |\n| `EditContext` | Context | Holds the editor factory. |\n| `WorkerPoolContext` | Context | Holds the worker pool. |\n| `VirtualizerContext` | Context | Holds the simple virtualizer. |\n| `GutterUtilitySlotStyles` | Value | Supplies style keys for gutter utility slots. |\n| `MergeConflictSlotStyles` | Value | Supplies style keys for merge conflict slots. |\n| `noopRender` | Function | Returns no React output for an optional render slot. |\n| `renderDiffChildren` | Function | Builds React portals for diff slots. |\n| `renderFileChildren` | Function | Builds React portals for file slots. |\n| `templateRender` | Function | Renders React content through a managed template slot. |\n","skills/diffs/references/api-rendering.md":"# Low-level rendering API\n\nThis reference lists the renderer, manager, DOM helper, comparison, and constant\nexports from `@pierre/diffs`.\n\n## Contents\n\n- [Renderers](#renderers)\n- [Interaction manager](#interaction-manager)\n- [Size, scroll, and render managers](#size-scroll-and-render-managers)\n- [Comparison helpers](#comparison-helpers)\n- [Syntax tree and DOM helpers](#syntax-tree-and-dom-helpers)\n- [Layout and CSS helpers](#layout-and-css-helpers)\n- [Constants](#constants)\n\n## Renderers\n\n| Export | Kind | Purpose |\n| -------------------------------------- | ----- | ------------------------------------------------------- |\n| `FileRenderer` | Class | Converts one file to highlighted HAST, CSS, and HTML. |\n| `FileRendererOptions` | Type | Adds header mode to base code options. |\n| `FileRenderResult` | Type | Holds file HAST, CSS, row counts, and buffers. |\n| `DiffHunksRenderer` | Class | Converts diff hunks to highlighted column HAST and CSS. |\n| `DiffHunksRendererOptions` | Type | Configures one hunk renderer. |\n| `DiffHunksRendererOptionsWithDefaults` | Type | Describes resolved hunk renderer options. |\n| `HunksRenderResult` | Type | Holds rendered diff columns, metadata, and row count. |\n| `RenderedLineContext` | Type | Supplies line state to a line decoration. |\n| `LineDecoration` | Type | Defines a custom line wrapper and injected rows. |\n| `InjectedRow` | Type | Defines one row inserted around a unified line. |\n| `SplitInjectedRow` | Type | Defines one row inserted around a split line. |\n| `UnifiedInjectedRowPlacement` | Type | Selects placement before or after a unified row. |\n| `SplitInjectedRowPlacement` | Type | Selects side and placement for a split row. |\n| `UnifiedLineDecorationProps` | Type | Supplies one unified row to a decoration. |\n| `SplitLineDecorationProps` | Type | Supplies paired split rows to a decoration. |\n\n## Interaction manager\n\n| Export | Kind | Purpose |\n| ------------------------------- | -------- | ------------------------------------------------------------------------ |\n| `InteractionManager` | Class | Handles hover, token, gutter, and line selection events. |\n| `InteractionManagerMode` | Type | Selects file or diff interaction data. |\n| `InteractionManagerBaseOptions` | Type | Defines interaction callbacks and enabled features. |\n| `InteractionManagerOptions` | Type | Adds required DOM access to base interaction options. |\n| `GetHoveredLineResult` | Type | Describes the current hovered file or diff line. |\n| `GetLineIndexUtility` | Type | Maps a logical line to row and column indexes. |\n| `OnLineClickProps` | Type | Describes a file line click. |\n| `OnLineEnterLeaveProps` | Type | Describes file line pointer entry or exit. |\n| `OnDiffLineClickProps` | Type | Describes a diff line click. |\n| `OnDiffLineEnterLeaveProps` | Type | Describes diff line pointer entry or exit. |\n| `OnTokenEventProps` | Type | Selects file or diff token event data. |\n| `SelectionWriteOptions` | Type | Configures callback emission, the active side, and line-only highlights. |\n| `MergeConflictActionTarget` | Type | Describes a merge conflict action element. |\n| `LogTypes` | Type | Selects interaction log categories. |\n| `pluckInteractionOptions` | Function | Selects interaction fields from component options. |\n\n## Size, scroll, and render managers\n\n| Export | Kind | Purpose |\n| --------------------------------- | -------- | ------------------------------------------------------------- |\n| `ResizeManager` | Class | Measures rows, annotations, and column CSS values. |\n| `ResizeManagerColumnVariableMode` | Type | Selects column variable measurement or application. |\n| `ResizeManagerSetupOptions` | Type | Configures annotation and column measurement. |\n| `ScrollSyncManager` | Class | Synchronizes additions and deletions column scroll positions. |\n| `queueRender` | Function | Adds a callback to the shared animation render queue. |\n| `dequeueRender` | Function | Removes a callback from the shared render queue. |\n| `clearRenderQueue` | Function | Removes all callbacks from the shared render queue. |\n\n## Comparison helpers\n\n| Export | Purpose |\n| ----------------------------- | ------------------------------------------------- |\n| `areDiffLineAnnotationsEqual` | Compares two diff annotation arrays. |\n| `areLineAnnotationsEqual` | Compares two file annotation arrays. |\n| `areDiffRenderOptionsEqual` | Compares resolved diff render options. |\n| `areFileRenderOptionsEqual` | Compares resolved file render options. |\n| `areDiffTargetsEqual` | Compares two diff interaction targets. |\n| `areFilesEqual` | Compares two file inputs. |\n| `areHunkDataEqual` | Compares two hunk data objects. |\n| `areObjectsEqual` | Performs the package's shallow object comparison. |\n| `areOptionsEqual` | Compares component option objects. |\n| `arePrePropertiesEqual` | Compares calculated `pre` properties. |\n| `areRenderRangesEqual` | Compares two render ranges. |\n| `areSelectionsEqual` | Compares editor selection arrays. |\n| `areThemesEqual` | Compares theme names or light/dark pairs. |\n| `areVirtualWindowSpecsEqual` | Compares two virtual window descriptions. |\n| `areWorkerStatsEqual` | Compares two worker statistics objects. |\n\n## Syntax tree and DOM helpers\n\n| Export | Kind | Purpose |\n| -------------------------------- | -------- | ---------------------------------------------------------- |\n| `createAnnotationElement` | Function | Creates a HAST annotation row from an annotation span. |\n| `createAnnotationWrapperNode` | Function | Creates a DOM host for an annotation slot. |\n| `createDiffSpanDecoration` | Function | Creates one inline diff decoration. |\n| `pushOrJoinSpan` | Function | Adds or joins one inline diff span. |\n| `createEmptyRowBuffer` | Function | Creates an empty virtual row buffer. |\n| `createFileHeaderElement` | Function | Creates a file or diff header HAST element. |\n| `CreateFileHeaderElementProps` | Type | Defines header source, mode, and sticky state. |\n| `createGutterGap` | Function | Creates a gutter gap HAST element. |\n| `createGutterItem` | Function | Creates a gutter item HAST element. |\n| `createGutterWrapper` | Function | Creates a gutter wrapper HAST element. |\n| `createGutterUtilityElement` | Function | Creates a gutter utility HAST element. |\n| `createGutterUtilityContentNode` | Function | Creates a gutter utility DOM content host. |\n| `createHastElement` | Function | Creates a typed HAST element. |\n| `createIconElement` | Function | Creates a sprite icon HAST element. |\n| `createTextNodeElement` | Function | Creates a HAST text node. |\n| `createNoNewlineElement` | Function | Creates the missing-final-newline HAST element. |\n| `createPreElement` | Function | Creates the outer HAST `pre` element. |\n| `createPreWrapperProperties` | Function | Creates HAST properties for a `pre` wrapper. |\n| `createRowNodes` | Function | Creates DOM row and content elements for one line. |\n| `createSeparator` | Function | Creates a hunk separator HAST element. |\n| `createSpanFromToken` | Function | Creates a HAST span from one highlighted token. |\n| `createStyleElement` | Function | Creates a DOM style element with an attribute marker. |\n| `createThemeStyleElement` | Function | Creates a marked theme style element. |\n| `createUnsafeCSSStyleNode` | Function | Creates a marked custom CSS style element. |\n| `findCodeElement` | Function | Finds the code element in a HAST tree. |\n| `getLineNodes` | Function | Gets rendered line nodes from a HAST root. |\n| `getOrCreateCodeNode` | Function | Reuses or creates a code column DOM node. |\n| `getLineAnnotationName` | Function | Creates the slot name for a line annotation. |\n| `getHunkSeparatorSlotName` | Function | Creates the slot name for a hunk separator. |\n| `getIconForType` | Function | Maps a file change type to a sprite icon. |\n| `processLine` | Function | Applies line render state to one HAST line. |\n| `setPreNodeProperties` | Function | Applies resolved render properties to a DOM `pre` element. |\n| `prerenderHTMLIfNecessary` | Function | Adds preloaded HTML to an empty host element. |\n\n## Layout and CSS helpers\n\n| Export | Purpose |\n| -------------------------------- | ------------------------------------------------------------- |\n| `createWindowFromScrollPosition` | Calculates a virtual window from scroll measurements. |\n| `isDefaultRenderRange` | Tests whether a render range covers the default full range. |\n| `prefersReducedMotion` | Reads the reduced-motion media preference. |\n| `formatCSSVariablePrefix` | Creates the global or token CSS variable prefix. |\n| `wrapCoreCSS` | Places core CSS in its cascade layer. |\n| `wrapThemeCSS` | Places theme CSS in its layer and mode selector. |\n| `wrapUnsafeCSS` | Places custom CSS in its cascade layer. |\n| `patchScrollbarGutterSize` | Updates the measured scrollbar gutter in theme CSS. |\n| `detachString` | Copies a retained substring to an independent backing string. |\n| `releaseStringDetachBuffer` | Resets the reusable string copy buffer. |\n| `SVGSpriteSheet` | Contains the SVG symbols used by rendered controls. |\n| `SVGSpriteNames` | Names a symbol in `SVGSpriteSheet`. |\n\n## Constants\n\n| Export | Purpose |\n| ------------------------------------------ | ----------------------------------------------------- |\n| `DEFAULT_THEMES` | Provides the default light and dark theme names. |\n| `DEFAULT_TOKENIZE_MAX_LENGTH` | Provides the default total tokenization limit. |\n| `DEFAULT_COLLAPSED_CONTEXT_THRESHOLD` | Provides the default hidden-context threshold. |\n| `DEFAULT_EXPANDED_REGION` | Provides the default hunk expansion state. |\n| `DEFAULT_RENDER_RANGE` | Provides the full render range. |\n| `EMPTY_RENDER_RANGE` | Provides an empty render range. |\n| `DEFAULT_VIRTUAL_FILE_METRICS` | Provides estimated file header and line heights. |\n| `DEFAULT_CODE_VIEW_FILE_METRICS` | Provides list item height estimates. |\n| `DEFAULT_CODE_VIEW_LAYOUT` | Provides an empty list layout. |\n| `DEFAULT_SMOOTH_SCROLL_SETTINGS` | Provides the default smooth scroll settings. |\n| `DIFFS_TAG_NAME` | Provides the `diffs-container` custom element name. |\n| `CORE_CSS_ATTRIBUTE` | Provides the core style marker attribute. |\n| `THEME_CSS_ATTRIBUTE` | Provides the theme style marker attribute. |\n| `UNSAFE_CSS_ATTRIBUTE` | Provides the custom style marker attribute. |\n| `DIFFS_SCROLLBAR_MEASURE_ATTRIBUTE` | Provides the scrollbar measurement attribute. |\n| `DIFFS_SCROLLBAR_GUTTER_MEASURED_PROPERTY` | Provides the measured scrollbar CSS property. |\n| `CODE_VIEW_HEADER_ATTRIBUTE` | Provides the list header host attribute. |\n| `CODE_VIEW_FOOTER_ATTRIBUTE` | Provides the list footer host attribute. |\n| `CUSTOM_HEADER_SLOT_ID` | Provides the custom header slot ID. |\n| `HEADER_PREFIX_SLOT_ID` | Provides the header prefix slot ID. |\n| `HEADER_FILENAME_SUFFIX_SLOT_ID` | Provides the filename suffix slot ID. |\n| `HEADER_METADATA_SLOT_ID` | Provides the header metadata slot ID. |\n| `HUNK_HEADER` | Provides the patch hunk header marker. |\n| `FILE_CONTEXT_BLOB` | Matches a patch hunk boundary. |\n| `INDEX_LINE_METADATA` | Provides the patch index metadata marker. |\n| `COMMIT_METADATA_SPLIT` | Provides the commit metadata separator expression. |\n| `FILENAME_HEADER_REGEX` | Matches a standard patch file header. |\n| `GIT_DIFF_FILE_BREAK_REGEX` | Matches a Git patch file boundary. |\n| `UNIFIED_DIFF_FILE_BREAK_REGEX` | Matches a unified patch file boundary. |\n| `MERGE_CONFLICT_START_MARKER_REGEX` | Matches a conflict start marker. |\n| `MERGE_CONFLICT_BASE_MARKER_REGEX` | Matches a conflict base marker. |\n| `MERGE_CONFLICT_SEPARATOR_MARKER_REGEX` | Matches a conflict separator marker. |\n| `MERGE_CONFLICT_END_MARKER_REGEX` | Matches a conflict end marker. |\n| `SPLIT_WITH_NEWLINES` | Splits text while it preserves newline tokens. |\n| `DIFFS_DEVELOPMENT_BUILD` | Reports whether the package uses a development build. |\n","skills/diffs/references/api-ssr.md":"# SSR API\n\nThis reference lists the SSR-specific exports from `@pierre/diffs/ssr`. The\nentry also re-exports every type in [Shared types](api-types.md).\n\n## Functions\n\n| Export | Purpose |\n| --------------------------- | ------------------------------------------------------------- |\n| `preloadFile` | Renders one file and returns props with `prerenderedHTML`. |\n| `preloadFileDiff` | Renders pre-parsed diff metadata and returns component props. |\n| `preloadMultiFileDiff` | Parses and renders an old and new file pair. |\n| `preloadPatchDiff` | Parses and renders one patch for `PatchDiff`. |\n| `preloadPatchFile` | Parses a multi-file patch and returns one result per file. |\n| `preloadUnresolvedFile` | Renders one merge-conflict file and returns component props. |\n| `preloadDiffHTML` | Renders a diff directly to an HTML string. |\n| `preloadUnresolvedFileHTML` | Renders a merge-conflict file directly to an HTML string. |\n| `renderHTML` | Serializes rendered HAST elements to HTML. |\n\n## Types\n\n| Export | Purpose |\n| ------------------------------ | -------------------------------------------------------- |\n| `PreloadFileOptions` | Defines input for `preloadFile`. |\n| `PreloadedFileResult` | Adds `prerenderedHTML` to file input. |\n| `PreloadDiffOptions` | Defines parsed or file-pair input for `preloadDiffHTML`. |\n| `PreloadFileDiffOptions` | Defines input for `preloadFileDiff`. |\n| `PreloadFileDiffResult` | Adds `prerenderedHTML` to parsed diff input. |\n| `PreloadMultiFileDiffOptions` | Defines input for `preloadMultiFileDiff`. |\n| `PreloadMultiFileDiffResult` | Adds `prerenderedHTML` to file-pair input. |\n| `PreloadPatchDiffOptions` | Defines input for `preloadPatchDiff`. |\n| `PreloadPatchDiffResult` | Adds `prerenderedHTML` to patch input. |\n| `PreloadPatchFileOptions` | Defines input for `preloadPatchFile`. |\n| `PreloadUnresolvedFileOptions` | Defines input for `preloadUnresolvedFile`. |\n| `PreloadUnresolvedFileResult` | Adds `prerenderedHTML` to merge-conflict input. |\n","skills/diffs/references/api-types.md":"# Shared types\n\nThis reference lists every export from the shared `@pierre/diffs` type module.\nThe root, React, and SSR entries re-export these types.\n\n## Contents\n\n- [Files and patches](#files-and-patches)\n- [Themes and options](#themes-and-options)\n- [Annotations and selection](#annotations-and-selection)\n- [`CodeView` types](#codeview-types)\n- [Lines, hunks, and render state](#lines-hunks-and-render-state)\n- [Render results and virtualization](#render-results-and-virtualization)\n- [Tokenization and diff types](#tokenization-and-diff-types)\n\n## Files and patches\n\n| Export | Purpose |\n| ------------------------------- | ----------------------------------------------------------------- |\n| `FileContents` | Describes a file name, text, language, header, and cache key. |\n| `DiffFileInput` | Accepts an old and new file for changes, additions, or deletions. |\n| `MaybeDiffFileInput` | Accepts a file pair or no file input. |\n| `FileDiffContentsLoader` | Loads complete files for partial diff metadata. |\n| `FileDiffLoadedChangedFiles` | Returns both files for a loaded changed diff. |\n| `FileDiffLoadedPureRenamedFile` | Returns the new file for a loaded pure rename. |\n| `FileDiffLoadedFiles` | Represents either loaded-file result. |\n| `ChangeTypes` | Names changed, renamed, added, or deleted file states. |\n| `ParsedPatch` | Holds patch metadata and parsed files. |\n| `ContextContent` | Describes one unchanged hunk block. |\n| `ChangeContent` | Describes one additions and deletions block. |\n| `Hunk` | Describes one parsed patch hunk. |\n| `FileDiffMetadata` | Holds parsed file names, lines, hunks, and change metadata. |\n| `MergeConflictMarkerRowType` | Names a merge conflict marker row. |\n| `MergeConflictMarkerRow` | Describes one marker row and its source line. |\n| `MergeConflictRegion` | Describes one parsed merge conflict region. |\n| `MergeConflictResolution` | Selects current, incoming, or both conflict contents. |\n| `MergeConflictActionPayload` | Describes one conflict action and region. |\n| `ProcessFileConflictData` | Holds state while patch parsing processes conflicts. |\n| `ConflictResolverTypes` | Names current, incoming, or both conflict choices. |\n\n## Themes and options\n\n| Export | Purpose |\n| ------------------------------------ | -------------------------------------------------------------- |\n| `SupportedLanguages` | Accepts a bundled, text, ANSI, or custom language name. |\n| `HighlighterTypes` | Selects shiki-js, shiki-wasm, or highlights. |\n| `HighlightedToken` | Stores a character index, foreground, and token text. |\n| `DiffsThemeNames` | Accepts a bundled or custom theme name. |\n| `ThemesType` | Maps light and dark schemes to theme names. |\n| `ThemeTypes` | Selects system, light, or dark mode. |\n| `DiffsHighlighter` | Defines backend-independent tokenization and theme resolution. |\n| `BaseCodeOptions` | Configures themes, wrapping, headers, tokenization, and CSS. |\n| `BaseDiffOptions` | Adds layout, indicators, context, and line diff options. |\n| `BaseDiffOptionsWithDefaults` | Describes required diff options after defaults apply. |\n| `DiffIndicators` | Selects classic, bar, or hidden diff indicators. |\n| `HunkSeparators` | Selects the hunk separator presentation. |\n| `LineDiffTypes` | Selects word, alternate word, character, or no inline diff. |\n| `FileHeaderRenderMode` | Selects a default or custom file header. |\n| `CustomPreProperties` | Defines custom properties for the rendered `pre` element. |\n| `PrePropertiesConfig` | Describes calculated `pre` element properties. |\n| `ExtensionFormatMap` | Maps file names or extensions to languages. |\n| `RenderHeaderPrefixCallback` | Produces prefix content for a diff header. |\n| `RenderHeaderFilenameSuffixCallback` | Produces filename suffix content for a diff header. |\n| `RenderHeaderMetadataCallback` | Produces metadata content for a diff header. |\n| `RenderFileMetadata` | Produces header content for a file. |\n| `PostRenderPhase` | Names mount, update, or unmount callback phases. |\n\n## Annotations and selection\n\n| Export | Purpose |\n| -------------------- | ----------------------------------------------------- |\n| `AnnotationSide` | Selects deletions or additions for an annotation. |\n| `LineAnnotation` | Associates metadata with one file line. |\n| `DiffLineAnnotation` | Associates metadata with one side and line. |\n| `AnnotationLineMap` | Groups diff annotations by line number. |\n| `SelectedLineRange` | Describes a selected start and end across diff sides. |\n| `SelectionSide` | Selects deletions or additions for a selection. |\n| `SelectionPoint` | Describes one line and optional side. |\n\n## `CodeView` types\n\n| Export | Purpose |\n| --------------------------------- | -------------------------------------------------------- |\n| `CodeViewFileItem` | Describes one file item in a virtualized list. |\n| `CodeViewDiffItem` | Describes one diff item in a virtualized list. |\n| `CodeViewItem` | Represents a file or diff list item. |\n| `CodeViewCreateEditorOptions` | Provides CodeView's routed editor option subset. |\n| `CodeViewItemEditCompleteHandler` | Handles completion with correlated event and item types. |\n| `CodeViewScrollBehavior` | Selects instant, smooth, or automatic smooth scroll. |\n| `CodeViewScrollTarget` | Represents any supported list scroll target. |\n| `CodeViewPositionScrollTarget` | Scrolls to an absolute list position. |\n| `CodeViewLineScrollTarget` | Scrolls to one item line. |\n| `CodeViewRangeScrollTarget` | Scrolls to one item line range. |\n| `CodeViewItemScrollTarget` | Scrolls to one item boundary. |\n| `NumericScrollLineAnchor` | Describes a numeric position inside a line. |\n| `CodeViewLayout` | Stores item offsets, heights, and total list height. |\n| `PendingCodeViewLayoutReset` | Describes a deferred list layout reset. |\n| `SmoothScrollSettings` | Configures duration and distance for smooth list scroll. |\n\n`CodeViewCreateEditorOptions` currently contains the routed `onChange(event)`\ncallback that `CodeView` uses to emit `onItemEditChange(event, item)`; it does\nnot add an item ID. A `CodeViewOptions.createEditor` factory also receives the\noptional `editStateKey` returned by `getEditStateKey(item)` as its third\nargument. Forward that key separately to the editor constructor. It retains the\neditable draft, undo/redo history, selections, and horizontal code scroll. Item\neditors never own CodeView's shared vertical position.\n\n`onItemEditComplete(event, item, nextItem)` must return `'accept'` to accept the\ncompleted item or `'reject'` to restore the original while the item remains\npresent; a missing callback rejects. During removal or teardown, neither\ndecision reinserts the item. Controlled owners must put the supplied `nextItem`\ninto their item state when accepting an item that should remain. If the item\nuses keyed render caching, assigning a fresh `cacheKey` to the accepted event\nfile or diff invalidates that cache.\n\n## Lines, hunks, and render state\n\n| Export | Purpose |\n| ---------------------------- | --------------------------------------------------------------- |\n| `HunkLineType` | Names context, expanded, addition, deletion, or metadata lines. |\n| `HunkData` | Describes one hunk's render indexes and line ranges. |\n| `HunkExpansionRegion` | Describes expanded context above and below a hunk. |\n| `ExpansionDirections` | Selects up, down, or both expansion directions. |\n| `DiffAcceptRejectHunkType` | Selects accept, reject, or both hunk controls. |\n| `DiffAcceptRejectHunkConfig` | Configures hunk accept and reject behavior. |\n| `GapSpan` | Describes an empty row span. |\n| `AnnotationSpan` | Describes an annotation row span. |\n| `LineSpans` | Represents a gap or annotation span. |\n| `LineTypes` | Names rendered context and change line classes. |\n| `LineInfo` | Describes a rendered line number, side, and type. |\n| `CodeColumnType` | Selects unified, additions, or deletions columns. |\n| `LineEventBaseProps` | Supplies a file line to an interaction callback. |\n| `DiffLineEventBaseProps` | Supplies a diff line and side to an interaction callback. |\n| `TokenEventBase` | Supplies a token and source event. |\n| `DiffTokenEventBaseProps` | Adds diff side data to a token event. |\n| `ObservedAnnotationNodes` | Stores DOM nodes for observed annotations. |\n| `ObservedGridNodes` | Stores DOM nodes for observed grid columns. |\n| `SharedRenderState` | Holds shared token transformer render state. |\n| `StickySpecs` | Describes sticky header position and height. |\n\n## Render results and virtualization\n\n| Export | Purpose |\n| --------------------------- | ------------------------------------------------------- |\n| `RenderFileOptions` | Defines the resolved options for a highlighted file. |\n| `RenderDiffOptions` | Defines the resolved options for a highlighted diff. |\n| `ForceFilePlainTextOptions` | Selects a plain-text file range. |\n| `ForceDiffPlainTextOptions` | Selects a plain-text diff range and hunk state. |\n| `ThemedFileResult` | Holds the highlighted file syntax tree and line count. |\n| `ThemedDiffResult` | Holds highlighted additions and deletions syntax trees. |\n| `RenderDiffFilesResult` | Holds the resolved old and new file inputs. |\n| `RenderFileResult` | Holds file output and the options that produced it. |\n| `RenderDiffResult` | Holds diff output and the options that produced it. |\n| `RenderedFileASTCache` | Stores one cached file syntax tree by theme. |\n| `RenderedDiffASTCache` | Stores one cached diff syntax tree by theme. |\n| `AppliedThemeStyleCache` | Stores applied light and dark theme CSS. |\n| `RenderRange` | Describes a start row, row count, and buffer sizes. |\n| `RenderWindow` | Describes first and last rows in a render window. |\n| `VirtualWindowSpecs` | Describes viewport position, height, and row window. |\n| `VirtualFileMetrics` | Describes estimated header and line heights. |\n\n## Tokenization and diff types\n\n| Export | Purpose |\n| ----------------------------------------------------- | -------------------------------------------------------------------- |\n| `DiffsTheme` | Shared editor colors with optional TextMate and Zed syntax palettes. |\n| `ThemedToken` | One styled token with content, offset, color, and optional styles. |\n| `TokensResult` | Token rows and root colors/styles. |\n| `CodeToTokensOptions`, `CodeToHtmlOptions` | Select a language, themes, and tokenization limits. |\n| `DiffsStreamTokenizer` | Incremental tokenization of appended chunks. |\n| `DiffsEditorTokenizer`, `DiffsEditorTokenizerOptions` | Incremental tokenization of document edits. |\n| `CreatePatchOptionsNonabortable` | Configures the underlying patch algorithm. |\n\nImport TextMate registration and Shiki transformer types from `shiki`. Diffs no\nlonger re-exports Shiki's public API.\n","skills/diffs/references/api-worker.md":"# Worker API\n\nThis reference lists every export from `@pierre/diffs/worker`, every public\n`WorkerPoolManager` member, and both worker script entries.\n\n## Runtime exports\n\n| Export | Kind | Purpose |\n| -------------------------------- | -------- | ----------------------------------------------------- |\n| `WorkerPoolManager` | Class | Runs file and diff highlighting across a worker pool. |\n| `getOrCreateWorkerPoolSingleton` | Function | Gets or creates the module-wide worker pool. |\n| `terminateWorkerPoolSingleton` | Function | Terminates and clears the module-wide worker pool. |\n\n## `WorkerPoolManager` members\n\n| Member | Purpose |\n| -------------------------------------------------------------- | ------------------------------------------------- |\n| `new WorkerPoolManager(options, renderOptions)` | Creates a worker pool. |\n| `initialize(languages?)` | Starts workers and loads languages. |\n| `isInitialized()` | Reports whether initialization finished. |\n| `isWorkingPool()` | Reports whether workers can accept work. |\n| `setRenderOptions(options)` | Updates theme and render settings in each worker. |\n| `getFileRenderOptions()` | Gets active file render options. |\n| `getDiffRenderOptions()` | Gets active diff render options. |\n| `highlightFileAST(instance, file)` | Queues a highlighted file result for an instance. |\n| `highlightDiffAST(instance, diff)` | Queues a highlighted diff result for an instance. |\n| `primeFileHighlightCache(file)` | Preloads one highlighted file result. |\n| `primeDiffHighlightCache(diff)` | Preloads one highlighted diff result. |\n| `getFileResultCache(file)` | Gets one cached file result. |\n| `getDiffResultCache(diff)` | Gets one cached diff result. |\n| `getPlainFileAST(file, start, total, lines?)` | Gets a plain-text file result. |\n| `getPlainDiffAST(diff, start, total, expansions?, threshold?)` | Gets a plain-text diff result. |\n| `inspectCaches()` | Gets both result caches. |\n| `evictFileFromCache(cacheKey)` | Removes one file cache entry. |\n| `evictDiffFromCache(cacheKey)` | Removes one diff cache entry. |\n| `subscribeToThemeChanges(instance)` | Subscribes a render instance to theme changes. |\n| `unsubscribeToThemeChanges(instance)` | Removes a theme subscription. |\n| `subscribeToStatChanges(callback)` | Subscribes to worker statistics. |\n| `cleanUpTasks(instance)` | Removes queued and active tasks for an instance. |\n| `getStats()` | Gets worker and cache statistics. |\n| `terminate()` | Stops workers and clears pool resources. |\n\n## Configuration and state types\n\n| Export | Purpose |\n| ----------------------------------- | ----------------------------------------------------------------- |\n| `SetupWorkerPoolProps` | Combines pool and highlighter options for the singleton. |\n| `WorkerPoolOptions` | Defines the worker factory, pool size, and cache size. |\n| `WorkerInitializationRenderOptions` | Defines initial languages, theme, highlighter, and diff settings. |\n| `WorkerRenderingOptions` | Defines the complete worker render settings. |\n| `WorkerStats` | Describes pool state, work counts, subscribers, and cache sizes. |\n| `WorkerRequestId` | Identifies one worker request. |\n| `ResolvedLanguage` | Holds a resolved language registration. |\n| `FileRendererInstance` | Defines callbacks for a file render consumer. |\n| `DiffRendererInstance` | Defines callbacks for a diff render consumer. |\n\n## Request and response types\n\n| Export | Purpose |\n| ------------------------------- | ------------------------------------------------------- |\n| `WorkerRequest` | Represents any request sent to a worker. |\n| `InitializeWorkerRequest` | Starts a worker with themes, languages, and options. |\n| `SetRenderOptionsWorkerRequest` | Updates render options and themes. |\n| `RenderFileRequest` | Requests one file render. |\n| `RenderDiffRequest` | Requests one diff render. |\n| `SubmitRequest` | Represents a file or diff request before ID assignment. |\n| `WorkerResponse` | Represents any worker response. |\n| `InitializeSuccessResponse` | Confirms worker initialization. |\n| `RegisterThemeSuccessResponse` | Confirms a render-option and theme update. |\n| `RenderSuccessResponse` | Represents a successful file or diff render. |\n| `RenderFileSuccessResponse` | Returns one file render result. |\n| `RenderDiffSuccessResponse` | Returns one diff render result. |\n| `RenderErrorResponse` | Returns a serialized worker error. |\n\n## Task types\n\n| Export | Purpose |\n| ---------------------------- | ------------------------------------------------- |\n| `AllWorkerTasks` | Represents any manager task. |\n| `InitializeWorkerTask` | Tracks one initialization request. |\n| `SetRenderOptionsWorkerTask` | Tracks one render-option update. |\n| `RenderFileTask` | Tracks one file render request and its consumers. |\n| `RenderDiffTask` | Tracks one diff render request and its consumers. |\n| `RenderTaskCallbacks` | Resolves or rejects one render task consumer. |\n\n## Worker script entries\n\n| Import | Purpose |\n| ----------------------------------------- | -------------------------------------------------------------------------------- |\n| `@pierre/diffs/worker/worker.js` | Supplies the module worker that uses package dependencies. |\n| `@pierre/diffs/worker/worker-portable.js` | Supplies a single script with all highlighter backends and dependencies bundled. |\n\nFor static hosting, copy `dist/worker/worker-portable.js` and start it with\n`new Worker(url)`. It also supports module workers and blob URLs, including VS\nCode webviews, without another bundling step. All backends are included in the\ndownload; only the selected backend is initialized. For lazy backend loading,\nuse the regular worker entry with your bundler.\n\nThe pool resolves themes and Shiki grammars on the main thread and sends them to\nthe worker. Their catalogs are excluded from the portable script.\n\nA pool is optional. When one is supplied, highlighting goes through its workers\nfor every backend. Highlights is often fast enough on the main thread to skip\nthe pool.\n","skills/diffs/references/recipe-annotations.md":"# Recipe: add line annotations and selection\n\nPass annotation data and a renderer to the surface:\n\n```tsx\nimport type { DiffLineAnnotation } from '@pierre/diffs/react';\nimport { MultiFileDiff } from '@pierre/diffs/react';\n\nconst annotations: DiffLineAnnotation<{ message: string }>[] = [\n {\n side: 'additions',\n lineNumber: 8,\n metadata: { message: 'Review this line.' },\n },\n];\n\n

{annotation.metadata.message}

}\n options={{\n enableLineSelection: true,\n onLineSelectionEnd(range) {\n saveSelection(range);\n },\n }}\n/>;\n```\n\nUse `LineAnnotation` for a single file. Use `DiffLineAnnotation` for a diff.\nControl the active selection with the `selectedLines` prop.\n","skills/diffs/references/recipe-code-view.md":"# Recipe: build a `CodeView`\n\nUse `CodeView` when one scroll region contains many files, diffs, or both. It\nmanages item virtualization, sticky headers, list-wide selection, and item or\nline scroll targets.\n\n## Contents\n\n- [Select item ownership](#select-item-ownership)\n- [Define items](#define-items)\n- [Use controlled React state](#use-controlled-react-state)\n- [Use imperative ownership](#use-imperative-ownership)\n- [Enable item edit mode](#enable-item-edit-mode)\n\n## Select item ownership\n\n| Host and data flow | Input | Update API |\n| ------------------------------------------- | ----------------- | ------------------------------------ |\n| React owns the complete list | `items` | Publish a new `items` array. |\n| React hosts a large or append-only list | `initialItems` | Use the `CodeViewHandle` methods. |\n| Vanilla JavaScript owns the viewer instance | `setItems(items)` | Use the `CodeView` instance methods. |\n\nKeep one ownership mode for the life of a mounted React viewer. Use controlled\nstate when item data already belongs to React. Use imperative ownership for a\nlarge or streamed list.\n\n## Define items\n\nGive each item a stable and unique `id`. Use a `file` item for `FileContents`.\nUse a `diff` item for `FileDiffMetadata`.\n\nIncrement `version` when an existing item changes its contents, annotations,\ncollapsed state, or edit state. `CodeView` uses the ID and version to select the\nitem that it must update.\n\n## Use controlled React state\n\n```tsx\nimport {\n parseDiffFromFile,\n type CodeViewItem,\n type CodeViewLineSelection,\n} from '@pierre/diffs';\nimport { CodeView, type CodeViewHandle } from '@pierre/diffs/react';\nimport { useRef, useState } from 'react';\n\nconst oldFile = {\n name: 'src/value.ts',\n contents: 'export const value = 1;',\n};\nconst newFile = {\n name: 'src/value.ts',\n contents: 'export const value = 2;',\n};\nconst codeViewStyle = { height: 600, overflow: 'auto' } as const;\nconst codeViewOptions = {\n theme: { light: 'pierre-light', dark: 'pierre-dark' },\n stickyHeaders: true,\n enableLineSelection: true,\n layout: { paddingTop: 16, paddingBottom: 16, gap: 12 },\n} as const;\n\nexport function ReviewSurface() {\n const viewerRef = useRef | null>(null);\n const [selection, setSelection] = useState(\n null\n );\n const [items, setItems] = useState(() => [\n {\n id: 'diff:src/value.ts',\n type: 'diff',\n fileDiff: parseDiffFromFile(oldFile, newFile),\n version: 0,\n },\n {\n id: 'file:README.md',\n type: 'file',\n file: { name: 'README.md', contents: '# Review notes' },\n version: 0,\n },\n ]);\n\n function toggleDiff() {\n setItems((current) =>\n current.map((item) =>\n item.id === 'diff:src/value.ts'\n ? {\n ...item,\n collapsed: !item.collapsed,\n version: (item.version ?? 0) + 1,\n }\n : item\n )\n );\n }\n\n return (\n <>\n \n \n viewerRef.current?.scrollTo({\n type: 'line',\n id: 'diff:src/value.ts',\n lineNumber: 1,\n side: 'additions',\n align: 'center',\n })\n }\n >\n Jump to change\n \n \n \n );\n}\n```\n\n## Use imperative ownership\n\nIn React, pass `initialItems` and keep `items` unset. Use the component ref to\ncall `addItems`, `getItem`, `updateItem`, `updateItemId`, or `scrollTo`.\n\nIn vanilla JavaScript, configure and populate the instance directly:\n\n```ts\nimport { CodeView, parseDiffFromFile } from '@pierre/diffs';\n\nconst root = document.querySelector('#review');\nif (root == null) throw new Error('Missing review host');\n\nconst oldFile = {\n name: 'src/value.ts',\n contents: 'export const value = 1;',\n};\nconst newFile = {\n name: 'src/value.ts',\n contents: 'export const value = 2;',\n};\n\nconst viewer = new CodeView({\n theme: { light: 'pierre-light', dark: 'pierre-dark' },\n stickyHeaders: true,\n enableLineSelection: true,\n onSelectedLinesChange(selection) {\n console.log('selected lines', selection);\n },\n});\n\nroot.style.height = '600px';\nroot.style.overflow = 'auto';\nviewer.setup(root);\nviewer.setItems([\n {\n id: 'diff:src/value.ts',\n type: 'diff',\n fileDiff: parseDiffFromFile(oldFile, newFile),\n version: 0,\n },\n]);\n\nviewer.addItems([\n {\n id: 'file:README.md',\n type: 'file',\n file: { name: 'README.md', contents: '# Review notes' },\n version: 0,\n },\n]);\nviewer.scrollTo({\n type: 'item',\n id: 'diff:src/value.ts',\n align: 'start',\n});\n\nconst item = viewer.getItem('diff:src/value.ts');\nif (item != null) {\n viewer.updateItem({\n ...item,\n collapsed: true,\n version: (item.version ?? 0) + 1,\n });\n}\n\nexport function removeReviewSurface() {\n viewer.cleanUp();\n}\n```\n\n## Enable item edit mode\n\nIn React, wrap `CodeView` in `EditProvider`. In vanilla JavaScript, pass\n`createEditor(editorType, options, editStateKey)` in `CodeViewOptions` and\nforward all three arguments to `new Editor`. Set `edit: true` on each editable\nitem and increment its version. The factory receives `'file'` or `'file-diff'`\nas its first argument so it can construct an editor of the requested type.\n\n`onItemEditChange(event, item)` reports live contents and annotation changes.\nRead the current document from `event.file`, the complete annotation collection\nfrom `event.lineAnnotations`. Treat it as a notification and do not feed the\nchanges back into the viewer.\n\n`onItemEditComplete(event, item, nextItem)` must return `'accept'` or `'reject'`\nwhenever a session ends, including when its final text is unchanged. `CodeView`\nbuilds `nextItem` with the completed contents and annotations, `edit: false`,\nand an incremented `version`. If you use keyed render caching, assign a fresh\n`cacheKey` to `event.file` or `event.fileDiff` before accepting. Return\n`'accept'` to install `nextItem` while the item remains present, or `'reject'`\nto restore the original item while it remains present. During removal or viewer\nteardown, neither decision reinserts the item. A missing callback rejects. When\nReact controls `items`, put `nextItem` into controlled state only when the item\nshould remain.\n\nUse `getEditStateKey(item)` to opt into retaining the draft, undo/redo history,\nselections, and editor-owned view state across editor instances. The returned\n`editStateKey` is passed to the editor factory. `getEditor(id)` returns the\ncurrent `Editor` instance.\n\nRead [Edit with React](recipe-edit-react.md) or\n[Edit with vanilla JavaScript](recipe-edit-vanilla.md) for the complete editor\nlifecycle.\n","skills/diffs/references/recipe-custom-highlighting.md":"# Recipe: register custom highlighting\n\nRegister themes before rendering. For a Zed-compatible theme with Highlights:\n\n```tsx\nimport { registerCustomTheme } from '@pierre/diffs';\nimport { FileDiff } from '@pierre/diffs/react';\n\nregisterCustomTheme('app-dark', () => import('./my-zed-theme.json'), 'zed');\n\n;\n```\n\nFor TextMate themes and custom grammars, use Shiki:\n\n```ts\nimport { registerCustomLanguage, registerCustomTheme } from '@pierre/diffs';\n\nregisterCustomLanguage(\n 'my-language',\n () => import('./my-language.tmLanguage.json'),\n ['myext']\n);\nregisterCustomTheme('my-theme', () => import('./my-textmate-theme.json'));\n```\n\nSet `file.lang` and `options.theme` to the registered names. Custom languages\napply to Shiki; Highlights bundles its lexers and ignores custom grammars.\n\nFor a CSS palette that works across backends:\n\n```ts\nimport { registerCustomCSSVariableTheme } from '@pierre/diffs';\n\nregisterCustomCSSVariableTheme('app-palette', {\n foreground: '#eeeeee',\n background: '#101010',\n 'token-keyword': '#c084fc',\n 'token-string-expression': '#86efac',\n});\n```\n\nThis registers a shared Diffs theme using `--diffs-*` variables. See\n[Highlighting API](api-highlighting.md#themes) for loader formats, name\nmatching, and CSS palette options.\n","skills/diffs/references/recipe-edit-react.md":"# Recipe: edit with React\n\nMount one `EditProvider` above the editable surfaces. Its factory receives the\neditor type, the surface's creation-time `editorOptions`, and an optional\n`editStateKey`. Each active surface or `CodeView` item owns its editor.\n\nPass `editStateKey` to opt into bounded in-memory retention of the draft,\nundo/redo history, selections, horizontal scroll, eligible vertical scroll, and\ndiff resume metadata across editor instances. Choose this key explicitly; it is\na stable application identity for the document. The same active key cannot be\nshared by two editors of the same type.\n\n## Contents\n\n- [Edit a standalone file or diff](#edit-a-standalone-file-or-diff)\n- [Keep annotations synchronized](#keep-annotations-synchronized)\n- [Edit CodeView items](#edit-codeview-items)\n\n## Edit a standalone file or diff\n\nSet `edit` on `File`, `FileDiff`, `MultiFileDiff`, or `PatchDiff`. Pass editor\ncreation options through `editorOptions` and optional retention through\n`editStateKey`.\n\n```tsx\nimport type { FileContents, FileDiffOptions } from '@pierre/diffs';\nimport {\n Editor,\n type EditorChangeEvent,\n type EditorFactory,\n type EditorOptions,\n type FileDiffEditCompleteEvent,\n} from '@pierre/diffs/edit';\nimport { EditProvider, MultiFileDiff, Virtualizer } from '@pierre/diffs/react';\nimport { useMemo, useRef, useState } from 'react';\n\nconst oldFile: FileContents = {\n name: 'src/value.ts',\n contents: 'export const value = 1;',\n};\nconst initialNewFile: FileContents = {\n name: 'src/value.ts',\n contents: 'export const value = 2;',\n};\nconst diffOptions: FileDiffOptions = {\n theme: { light: 'pierre-light', dark: 'pierre-dark' },\n diffStyle: 'split',\n};\n\nconst createEditor: EditorFactory = (\n editorType,\n options,\n editStateKey?: string\n) => new Editor(editorType, options, editStateKey);\n\nexport function EditableDiff() {\n const [edit, setEdit] = useState(false);\n const [newFile, setNewFile] = useState(initialNewFile);\n const editorRef = useRef | null>(null);\n const editorOptions = useMemo<\n EditorOptions<'file-diff', undefined, undefined>\n >(\n () => ({\n onAttach(editor) {\n editorRef.current = editor;\n },\n }),\n []\n );\n\n function toggleEdit() {\n setEdit((value) => !value);\n }\n\n function handleEditChange(\n event: EditorChangeEvent<'file-diff', undefined, undefined>\n ) {\n saveDraft(event.file);\n }\n\n function handleEditComplete(\n event: FileDiffEditCompleteEvent\n ) {\n if (event.newFile != null) {\n setNewFile(event.newFile);\n }\n return 'accept' as const;\n }\n\n return (\n \n \n editorRef.current?.undo()}\n >\n Undo\n \n \n \n \n \n );\n}\n```\n\nMount the provider near the application root when many surfaces use edit mode.\nAlways forward all three factory arguments. Use `onAttach` when controls need\n`undo`, `redo`, `applyEdits`, selections, markers, focus, or other editor APIs.\n`EditStateManager` only manages sessions retained with `editStateKey`; unkeyed\nsessions require no manager cleanup. For keyed sessions, use\n`EditStateManager.clear(type, key)` after a session becomes inactive when its\nretained draft should be discarded. `clearAll()` clears inactive state in both\nnamespaces, and `setCapacity(capacity)` changes each namespace's default limit\nof 100 entries. Active state is never mutated by manager clearing.\n\n## Keep annotations synchronized\n\nEdit mode owns annotation positions during an active session. Change events\nexpose the remapped collection for observation, but do not feed it back into the\nsurface. On acceptance, store the completion event's final annotations beside\nthe accepted file or diff. Use `isFileAnnotationCollection` or\n`isDiffAnnotationCollection` when the surface type is not already known, and key\nannotation UI state by a stable metadata ID instead of a line number.\n\n## Edit `CodeView` items\n\nWrap `CodeView` in the same `EditProvider`. Set `edit: true` on an item and\nincrement its `version`. Pass shared creation options through the `CodeView`\n`editorOptions` prop. Use `getEditStateKey(item)` for opt-in draft, history,\nselection, and view-state retention.\n\nUse `onItemEditChange` for live contents and annotation changes. Use\n`onItemEditComplete` to accept or reject every ended session, including when its\nfinal text is unchanged. If you use keyed render caching, assign a fresh\n`cacheKey` to the event's file or diff. Put the supplied `nextItem` into\ncontrolled state only while the item should remain, then return `'accept'`;\nacceptance during removal or teardown does not reinsert it. `CodeView` builds\n`nextItem` with `edit: false` and an incremented `version`.\n\n`CodeViewHandle.getEditor(id)` returns the current `Editor` instance. The item\neditor keeps its active document and history when virtualization or collapse\nremoves the item from the rendered window. `getEditStateKey` extends that\nretention to later editor instances after the edit session ends.\n\nWhen a worker pool highlights an editable surface, set\n`useTokenTransformer: true` in the worker `highlighterOptions`.\n","skills/diffs/references/recipe-edit-vanilla.md":"# Recipe: edit with vanilla JavaScript\n\nRender a standalone surface first. Then attach one `Editor` to it. Use one\neditor for each surface that can be edited at the same time.\n\n## Contents\n\n- [Edit a standalone diff](#edit-a-standalone-diff)\n- [Edit CodeView items](#edit-codeview-items)\n\n## Edit a standalone diff\n\n```ts\nimport {\n FileDiff,\n type DiffLineAnnotation,\n type FileContents,\n} from '@pierre/diffs';\nimport { Editor } from '@pierre/diffs/edit';\n\ninterface ThreadMetadata {\n id: string;\n}\n\nconst hostElement = document.querySelector('#diff');\nif (hostElement == null) throw new Error('Missing diff host');\nconst host: HTMLElement = hostElement;\n\nconst oldFile: FileContents = {\n name: 'src/value.ts',\n contents: 'export const value = 1;',\n};\nlet newFile: FileContents = {\n name: 'src/value.ts',\n contents: 'export const value = 2;',\n};\nlet annotations: DiffLineAnnotation[] = [\n {\n side: 'additions',\n lineNumber: 1,\n metadata: { id: 'value-review' },\n },\n];\nconst view = new FileDiff({\n theme: { light: 'pierre-light', dark: 'pierre-dark' },\n onEditChange(event) {\n saveDraft(event.file);\n },\n onEditComplete(event) {\n if (event.newFile != null) {\n newFile = event.newFile;\n }\n if (event.lineAnnotations != null) {\n annotations = event.lineAnnotations;\n }\n return 'accept';\n },\n renderAnnotation(annotation) {\n const element = document.createElement('p');\n element.textContent = 'Thread ' + annotation.metadata.id;\n return element;\n },\n});\n\nfunction render() {\n view.render({\n fileContainer: host,\n oldFile,\n newFile,\n lineAnnotations: annotations,\n });\n}\n\nrender();\n\nconst editor = new Editor<'file-diff', ThreadMetadata>(\n 'file-diff',\n {},\n 'src/value.ts:draft'\n);\nlet finishEditing: (() => void) | undefined = editor.edit(view);\n\nexport function stopEditing() {\n const finish = finishEditing;\n finishEditing = undefined;\n finish?.();\n}\n\nexport function removeSurface() {\n stopEditing();\n view.cleanUp();\n}\n```\n\n`onEditChange` receives one `EditorChangeEvent`. Observe its remapped\n`lineAnnotations`, but do not feed them back into the surface during the active\nsession. Store the final collection from `onEditComplete` alongside the accepted\nfile or diff. Use stable metadata IDs for application state that belongs to an\nannotation.\n\nPass a third `editStateKey` argument to `new Editor` when a later editor\ninstance should resume/save the in-memory draft, undo/redo history, selections,\nand editor-owned view state.\n\nUse `VirtualizedFile` or `VirtualizedFileDiff` with a `Virtualizer` for a large\nstandalone surface. Load `@pierre/diffs/edit` with `import()` when edit mode is\noptional and the initial bundle must omit the editor.\n\n## Edit `CodeView` items\n\nPass a factory through `CodeViewOptions.createEditor`:\n\n```ts\nimport { CodeView } from '@pierre/diffs';\nimport { Editor } from '@pierre/diffs/edit';\n\nexport function mountEditableCodeView(root: HTMLElement) {\n const viewer = new CodeView({\n getEditStateKey(item) {\n return 'draft:' + item.id;\n },\n createEditor(editorType, options, editStateKey) {\n return new Editor(editorType, options, editStateKey);\n },\n onItemEditChange(event, item) {\n saveItemDraft(item.id, event.file, event.lineAnnotations);\n },\n onItemEditComplete(event, item, nextItem) {\n if (item.type !== 'file' || !('file' in event)) return 'reject';\n\n // Re-key only if this item participates in keyed render caching.\n event.file.cacheKey = item.id + ':v' + nextItem.version;\n return 'accept';\n },\n });\n\n viewer.setup(root);\n viewer.setItems([\n {\n id: 'file:src/value.ts',\n type: 'file',\n file: {\n name: 'src/value.ts',\n contents: 'export const value = 1;',\n },\n edit: true,\n version: 0,\n },\n ]);\n\n return viewer;\n}\n```\n\nSet `edit: true` on an item and increment its `version`. `onItemEditChange`\nreceives `(event, item)`; use `event.file` and `event.lineAnnotations` without\nfeeding the change back into the viewer. Completion receives\n`(event, item, nextItem)` whenever a session ends, including when its final text\nis unchanged. `CodeView` builds `nextItem` with the final contents and\nannotations, `edit: false`, and an incremented `version`. If you use keyed\nrender caching, assign a fresh `cacheKey` to `event.file` or `event.fileDiff`.\nReturn `'accept'` to install `nextItem` while the item remains present or\n`'reject'` to restore the original item while it remains present. During removal\nor viewer teardown, neither decision reinserts the item. A missing completion\ncallback rejects. A controlled React owner should put `nextItem` into its\n`items` state only when the item should remain.\n\n`getEditStateKey(item)` opts an item into draft, undo/redo, selection, and\neditor-owned view-state retention across editor instances. Forward the resulting\nthird factory argument to `new Editor`. `CodeView` creates and removes the item\neditors.\n\n`viewer.getEditor(id)` returns the current `Editor` instance. Call\n`viewer.cleanUp()` when the host removes the viewer.\n\nWhen a worker pool highlights an editable surface, set\n`useTokenTransformer: true` in the worker `highlighterOptions`.\n","skills/diffs/references/recipe-react.md":"# Recipe: render with React\n\n## Select a surface\n\n| Input or layout | Component |\n| ------------------------------------------- | ---------------- |\n| One `FileContents` object | `File` |\n| Old and new `FileContents` objects | `MultiFileDiff` |\n| Existing `FileDiffMetadata` | `FileDiff` |\n| One unified patch string | `PatchDiff` |\n| One file with merge conflicts | `UnresolvedFile` |\n| One scroll region with many files and diffs | `CodeView` |\n\nUse `MultiFileDiff` when the app has old and new file contents:\n\n```tsx\nimport { MultiFileDiff } from '@pierre/diffs/react';\n\n;\n```\n\nPass source data, annotations, and slot renderers as component props. Pass\ndisplay, theme, interaction, and highlighting settings through `options`.\n\nKeep file objects and option objects stable when their values do not change.\nWrap a large standalone surface in `Virtualizer`. Use `CodeView` when one scroll\nregion contains a list of files or diffs.\n\nUse the matching preload function from `@pierre/diffs/ssr` when the server must\nrender the initial highlighted markup.\n","skills/diffs/references/recipe-ssr.md":"# Recipe: preload a diff on the server\n\nCreate props on the server and pass the result to the matching React component:\n\n```tsx\nimport { preloadMultiFileDiff } from '@pierre/diffs/ssr';\nimport { MultiFileDiff } from '@pierre/diffs/react';\n\nconst preloaded = await preloadMultiFileDiff({\n oldFile: { name: 'src/value.ts', contents: oldSource },\n newFile: { name: 'src/value.ts', contents: newSource },\n options: { theme: 'pierre-dark', diffStyle: 'split' },\n});\n\n;\n```\n\nSelect the preload function that matches the client component. Use\n`preloadDiffHTML` or `preloadUnresolvedFileHTML` when the host needs an HTML\nstring only.\n","skills/diffs/references/recipe-vanilla.md":"# Recipe: render with vanilla JavaScript\n\n## Select a surface\n\n| Input or layout | Class |\n| ------------------------------------------- | --------------------- |\n| One `FileContents` object | `File` |\n| Existing or parsed `FileDiffMetadata` | `FileDiff` |\n| One file with merge conflicts | `UnresolvedFile` |\n| One large file | `VirtualizedFile` |\n| One large diff | `VirtualizedFileDiff` |\n| One scroll region with many files and diffs | `CodeView` |\n\nParse the files, create the view, and render it into a host:\n\n```ts\nimport { FileDiff, parseDiffFromFile } from '@pierre/diffs';\n\nconst host = document.querySelector('#diff');\nif (host == null) throw new Error('Missing diff host');\n\nconst fileDiff = parseDiffFromFile(\n { name: 'src/value.ts', contents: oldSource },\n { name: 'src/value.ts', contents: newSource }\n);\n\nconst view = new FileDiff({\n diffStyle: 'split',\n theme: 'pierre-dark',\n});\n\nview.render({ fileContainer: host, fileDiff });\n```\n\nKeep the class instance while the host remains mounted. Call `render` again when\nthe source data changes. Call `setOptions`, `setThemeType`,\n`setLineAnnotations`, or `setSelectedLines` for targeted updates.\n\nUse a `Virtualizer` with `VirtualizedFile` or `VirtualizedFileDiff` for one\nlarge surface. Use `CodeView` for a list that shares one scroll region. Call\n`cleanUp()` when the host removes the surface.\n","skills/diffs/references/recipe-workers.md":"# Recipe: use a worker pool\n\nWrap React diff surfaces in one provider:\n\n```tsx\nimport { WorkerPoolContextProvider } from '@pierre/diffs/react';\n\n\n new Worker(new URL('@pierre/diffs/worker/worker.js', import.meta.url), {\n type: 'module',\n }),\n }}\n highlighterOptions={{\n langs: ['typescript', 'tsx'],\n theme: { light: 'pierre-light', dark: 'pierre-dark' },\n }}\n>\n {children}\n;\n```\n\nFor vanilla JavaScript, call `getOrCreateWorkerPoolSingleton` and pass the\nresult as the second constructor argument to a render class. Call\n`terminateWorkerPoolSingleton()` when the application tears down the shared\npool.\n","skills/highlights/SKILL.md":"---\nname: highlights\ndescription:\n Use when an app uses @pierre/highlights to generate syntax-highlighted HTML or\n tokens, stream code, incrementally tokenize edits, or apply Zed-compatible\n themes and CSS variables.\n---\n\n# `@pierre/highlights`\n\nUse `@pierre/highlights` for standalone syntax highlighting with built-in\nWebAssembly lexers. Choose HTML for a complete code block, tokens for a custom\nrenderer, `StreamTokenizer` for append-only input, or `LiveTokenizer` for an\neditable document.\n\n## Install\n\n```bash\npnpm add @pierre/highlights\n```\n\nImport from `@pierre/highlights`. Conditional exports initialize WebAssembly\nautomatically for Node.js, browsers, and Cloudflare Workers. Highlighting is\nsynchronous after import; ordinary usage needs no `init()` or language\nregistration.\n\n## Select a reference\n\n| Task | Reference |\n| -------------------------------------------------------------------------- | ----------------------------------------- |\n| Generate HTML or tokens, validate a language, or manage a Wasm module | [Rendering](references/rendering.md) |\n| Load or customize themes, switch CSS variables, or render multiple schemes | [Themes](references/themes.md) |\n| Tokenize streamed strings or bytes | [Streaming](references/streaming.md) |\n| Apply edits, prioritize a viewport, or read packed token records | [Incremental editing](references/live.md) |\n\nFor file, diff, or editor components, read the [diffs skill](../diffs/SKILL.md).\n","skills/highlights/references/live.md":"# Incremental editing\n\n`LiveTokenizer` owns a document and an isolated WebAssembly instance. It\nre-tokenizes changed lines and following lines until the lexer state converges\nwith the retained state. Constructor options extend the\n[tokenization options](rendering.md#options-and-languages) with `code` (default\nempty), `renderRange`, and `onDeferTokenize`.\n\n## Apply edits\n\n```ts\nimport { LiveTokenizer } from '@pierre/highlights';\nimport { pierreDark } from '@pierre/highlights/themes';\n\nconst live = new LiveTokenizer({\n code: 'const answer = 41;\\nconsole.log(answer);',\n lang: 'ts',\n theme: pierreDark,\n});\n\ntry {\n const update = live.applyEdits([\n {\n range: {\n start: { line: 0, character: 15 },\n end: { line: 0, character: 17 },\n },\n newText: '42',\n },\n ]);\n\n console.log(live.getLineText(0)); // const answer = 42;\n for (const change of update.lineChanges) {\n for (let line = change.newStartLine; line < change.newEndLine; line++) {\n console.log(line, live.getLineTokens(line));\n }\n }\n} finally {\n live.dispose();\n}\n```\n\nEvery edit range uses zero-based lines and UTF-16 character positions in the\ndocument before the batch. The end position is exclusive. Overlapping ranges are\nrejected before mutation. `reset(code, options?)` replaces the whole text while\nretaining language and theme options; recreate the tokenizer to change those\noptions.\n\nWithout `renderRange`, updates finish synchronously and `update.lines` is empty.\nUse `lineChanges` and `getLineTokens()` to refresh a renderer. Each\n`LiveLineChange` maps `[oldStartLine, oldEndLine)` to\n`[newStartLine, newEndLine)`; also remove deleted rows when reconciling a view.\n`LiveTokenizerUpdate` includes `revision`, `previousLineCount`, and `lineCount`.\n\n`getLineTokens(line)` returns `{ tokens, bracketIgnoredRanges }`. Its token\noffsets are relative to that line. `bracketIgnoredRanges` contains end-exclusive\nUTF-16 column pairs for strings, comments, and regexes that bracket matching\nshould skip.\n\n## Prioritize a viewport\n\n`renderRange: [startLine, endLine]` uses post-edit line numbers and excludes\n`endLine`. Pass it on each update that should prioritize a viewport. Dirty lines\nbefore the viewport must also be processed to establish lexer state; the\nremaining work runs in background slices.\n\n```ts\nimport { LiveTokenizer } from '@pierre/highlights';\nimport { pierreDark } from '@pierre/highlights/themes';\n\nconst live = new LiveTokenizer({\n code: 'const answer = 41;\\nconsole.log(answer);',\n lang: 'ts',\n theme: pierreDark,\n renderRange: [0, 1],\n onDeferTokenize(lines) {\n // This callback can run before the constructor returns.\n for (const [line, tokens] of lines) console.log(line, tokens);\n },\n});\n\ntry {\n console.log(live.getLineTokens(0)); // Read the initial viewport after construction.\n const update = live.applyEdits(\n [\n {\n range: {\n start: { line: 0, character: 15 },\n end: { line: 0, character: 17 },\n },\n newText: '42',\n },\n ],\n { renderRange: [0, 1] }\n );\n for (const [line, tokens] of update.lines) console.log(line, tokens);\n\n live.flush(); // Finish pending work before reading the complete document's tokens.\n} finally {\n live.dispose();\n}\n```\n\n`update.lines` contains re-tokenized lines inside the range, not the entire\nviewport. Finished lines outside it arrive through `onDeferTokenize`, which can\nrun synchronously during construction or an update. Keep the callback\nindependent of the variable receiving the new instance. Schedule further edits\nafter the current update; calling `applyEdits()` or `reset()` inside its\nsynchronous callback throws.\n\nBoth maps contain `HighlightedToken[]`: tuples of\n`[character, foregroundColor, text]` using the first resolved theme. Read\n`getLineTokens()` when font styles or multi-theme `htmlStyle` maps are needed.\nWhile `pendingTokenization` is true, unreached lines can retain old tokens and\nnew lines can have foreground-only tokens. Call `flush()` before reads that\nrequire fully current tokens.\n\n## Document and lifecycle API\n\n| Member | Purpose |\n| ---------------------------------------------- | ---------------------------------------------------------------------------- |\n| `revision`, `lineCount`, `pendingTokenization` | Read document revision, line count, and pending work |\n| `applyEdits(edits, options?)` | Apply a batch and return `LiveTokenizerUpdate` |\n| `reset(code, options?)` | Replace text and return `LiveTokenizerUpdate` |\n| `getLineLength(line)`, `getLineText(line)` | Read UTF-16 length or text excluding the terminator |\n| `getText()` | Read all text, preserving LF, CRLF, and lone CR |\n| `getLineTokens(line)` | Read themed tokens and bracket-ignored ranges |\n| `getLineRecords(line)` | Read packed raw token records |\n| `flush(endLine?)` | Finish pending work before an exclusive line bound, or all work when omitted |\n| `pause()`, `resume()` | Suspend or resume background tokenization |\n| `dispose()` | Release the instance and cancel deferred work; safe to repeat |\n\n`flush()`, `reset()`, and `applyEdits()` (even a no-op batch) resume paused\nwork. After disposal, other methods and state getters throw. Keep one tokenizer\nfor the document's lifetime and dispose it when the editor unmounts or closes.\n\n## Packed records\n\n`getLineRecords()` returns `LiveTokenRecords` with `revision`, `format`, and\n`data: Uint32Array`. Starts are implicit: zero for the first token, then the\nprevious token's end. End positions are UTF-16 columns within the line.\n\n| Format | Encoding |\n| ---------- | -------------------------------------------------------------------- |\n| `packed24` | One word per token: `tokenId = word >>> 24`, `end = word & 0xffffff` |\n| `wide32` | Pairs of `[endUtf16, tokenId]` for lines exceeding the 24-bit range |\n\nImport `tokenNames` from `@pierre/highlights` to map IDs to syntax scope names.\nViews are invalidated by successful edits, resets, deferred tokenization slices,\nand disposal. Copy `records.data.slice()` before retaining data across those\noperations. Deferred work can invalidate data without changing the document\nrevision.\n\nThe root entry exports `HighlightedToken`, `LiveLineChange`, `LivePosition`,\n`LiveTextEdit`, `LiveTokenizerOptions`, `LiveTokenizerUpdate`,\n`LiveTokenRecords`, and `LiveUpdateOptions`. Use `LivePosition` and\n`LiveTextEdit` for the public position and edit types.\n","skills/highlights/references/rendering.md":"# Rendering\n\n## HTML\n\n```ts\nimport { codeToHtml } from '@pierre/highlights';\nimport { pierreDark } from '@pierre/highlights/themes';\n\nconst html = new TextDecoder().decode(\n codeToHtml('const answer = 42;', { lang: 'ts', theme: pierreDark })\n);\n```\n\n`codeToHtml()` returns UTF-8 bytes for a\n`
…
` fragment. Source text is\nHTML-escaped and theme styles are applied inline. Decode the bytes immediately,\nor call `.slice()` before retaining them across another highlighting or\ntokenization call on the same highlighter. The top-level `codeToHtml()` and\n`codeToTokens()` share one instance.\n\n## Tokens\n\n```ts\nimport { codeToTokens } from '@pierre/highlights';\nimport { pierreDark } from '@pierre/highlights/themes';\n\nconst result = codeToTokens('const answer = 42;\\n', {\n lang: 'ts',\n theme: pierreDark,\n});\n\nconsole.log(result.tokens[0]); // ThemedToken[] for the first line\nconsole.log(result.fg, result.bg); // Root foreground and background colors\n```\n\n`TokensResult.tokens` contains one `ThemedToken[]` per line. Line terminators\nare excluded from content; a trailing line break adds an empty final line.\nOffsets count UTF-16 code units from the start of the complete input.\n\n| Token field | Meaning |\n| ---------------------- | ----------------------------------------------------------------------------- |\n| `content`, `offset` | Text and its absolute UTF-16 start index |\n| `color`, `fontStyle` | Single-theme color and Shiki-style font flags |\n| `htmlStyle` | Multi-theme styles, including custom properties; apply the whole map |\n| `type` | `1` comment, `2` string, `3` regex, otherwise `0` or omitted |\n| `bgColor`, `htmlAttrs` | Optional background and span attributes for renderer/transformer integrations |\n\nHighlights emits italic (`1`) and bold (`2`) font flags. The type also supports\nunderline (`4`) and strikethrough (`8`) supplied by transformers. Use text nodes\nor escape `content` in a custom HTML renderer. Apply root colors as well as\ntoken styles. Token objects are Shiki-compatible; lexer boundaries and syntax\nclassifications can differ.\n\nWith multiple themes, `fg` and `bg` can contain CSS declaration lists, and\n`defaultColor: false` supplies `rootStyle`. See [Themes](themes.md) for\nrendering those styles. Equal runs can share an `htmlStyle` object; replace that\nobject when customizing one token.\n\n## Options and languages\n\nBoth functions accept `string`, `Uint8Array`, or `ArrayBuffer` input; bytes are\nUTF-8. Supply `lang` and exactly one of `theme` or `themes`.\n\n| Option | Meaning |\n| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- |\n| `lang` | Built-in language name or alias, typed as `Lang` |\n| `theme` | One Zed `Theme` or `ThemeFamily` object |\n| `themes` | Non-empty map of named theme objects; see [Themes](themes.md) |\n| `cssVariablePrefix` | Prefix for CSS-variable colors and theme properties; default `--hls-` |\n| `defaultColor` | With `themes`, inline theme key (default `light`), `false`, or `'light-dark()'` |\n| `tokenizeMaxLineLength` | Tokenization only: lines at or above this UTF-16 length become one token without syntax styling; `0` or omission disables it |\n\nThe line-length limit reduces token objects, while the lexer still processes the\nline to preserve subsequent state. It also applies to streaming and live\ntokenization, but is not an HTML option.\n\nLanguage names and aliases are case-insensitive. Unknown names throw\n`RangeError`. Highlights performs no automatic language detection or filename\nresolution. Validate external labels and choose an explicit fallback:\n\n```ts\nimport { isSupportedLanguage } from '@pierre/highlights';\n\nconst requestedLanguage: string = 'typescript';\nconst lang = isSupportedLanguage(requestedLanguage)\n ? requestedLanguage\n : 'plain';\n```\n\n`isSupportedLanguage()` narrows a string to `Lang`. Plain text aliases include\n`plain`, `text`, `plaintext`, and `txt`. Lexers are built in; custom TextMate\ngrammar registration belongs to the Shiki APIs in `@pierre/diffs`.\n\n## Runtime and types\n\n`createHighlighter()` returns an isolated `Highlighter` using the initialized\nmodule. Embedders can pass their own compiled `WebAssembly.Module` to\n`createHighlighter(module)` or replace the shared highlighter with\n`init(module)`. Both functions are synchronous. `Highlighter` exposes\n`codeToHtml()` and `codeToTokens()` with the signatures above. Import the normal\npackage entry for automatic initialization.\n\nCore public types are `Highlighter`, `Lang`, `CodeToHtmlBaseOptions`,\n`CodeToHtmlOptions`, `CodeToTokensBaseOptions`, `CodeToTokensOptions`,\n`ThemeOptions`, `ThemedToken`, and `TokensResult`. Theme types are covered in\n[Themes](themes.md); live types and `tokenNames` in\n[Incremental editing](live.md).\n","skills/highlights/references/streaming.md":"# Streaming\n\n`StreamTokenizer` extends `TransformStream`. It takes\nthe [tokenization options](rendering.md#options-and-languages) and owns an\nisolated WebAssembly instance. Use it for append-only input; use\n[LiveTokenizer](live.md) when previously received text can change.\n\n## Pipe a readable stream\n\nPass a UTF-8 byte stream through the tokenizer with `pipeThrough()`. It decodes\nbytes internally, including characters split across chunks. Given an existing\n`ReadableStream` named `responseBody`:\n\n```ts\nimport { StreamTokenizer } from '@pierre/highlights';\nimport { pierreDark } from '@pierre/highlights/themes';\n\nconst lines = responseBody.pipeThrough(\n new StreamTokenizer({ lang: 'ts', theme: pierreDark })\n);\n\nfor await (const tokens of lines) {\n console.log(tokens); // One ThemedToken[] per line\n}\n```\n\nClosing the writable side emits the remaining lines and releases the instance.\nCancellation or abort discards buffered input and releases it. Let the stream\npipeline manage completion; use the synchronous methods below when manually\nfeeding strings or UTF-8 bytes.\n\n## Push chunks synchronously\n\n```ts\nimport { StreamTokenizer } from '@pierre/highlights';\nimport { pierreDark } from '@pierre/highlights/themes';\n\nconst stream = new StreamTokenizer({ lang: 'ts', theme: pierreDark });\n\ntry {\n console.log(stream.pushCode('const answer =')); // []: incomplete line\n const bytes = new TextEncoder().encode(' 42;\\nconsole.log(answer);');\n console.log(stream.pushCode(bytes)); // First line\n console.log(stream.end()); // Remaining line; also disposes the instance\n} finally {\n stream.dispose();\n}\n```\n\n| Method | Behavior |\n| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |\n| `pushCode(chunk: string \\| Uint8Array)` | Accepts text or UTF-8 bytes; returns `ThemedToken[][]` for completed lines and buffers the unfinished line |\n| `end()` | Finishes decoding and returns remaining lines, including an empty final line after a trailing terminator, then disposes |\n| `dispose()` | Discards buffered input and releases the instance; safe to repeat |\n\nChunks can produce zero or more lines. Lines are emitted when `\\n` arrives,\nincluding in CRLF input, or at `end()`. Lexer state is retained across chunks.\nToken offsets are UTF-16 indices from the start of the complete stream. Apply\nthe same token styles described in [Rendering](rendering.md#tokens).\n\nCall `end()` once when input finishes. Calling `pushCode()` or `end()` after\ndisposal throws. Keep `dispose()` in cleanup paths for cancellation and errors.\n\nUTF-8 characters can span consecutive byte chunks. Mixing strings and bytes\npreserves chunk order: a nonempty string flushes incomplete UTF-8 as a\nreplacement character before appending the string. Empty chunks leave buffered\ninput intact.\n","skills/highlights/references/themes.md":"# Themes\n\nHighlights takes Zed-compatible theme objects. Load them from\n`@pierre/highlights/themes`; `@pierre/theme` supplies Shiki and VS Code objects\nwith a different shape.\n\n## Load a theme\n\n```ts\nimport { pierreDark } from '@pierre/highlights/themes';\nimport vitesseDark from '@pierre/highlights/themes/vitesse-dark';\nimport { themes } from '@pierre/highlights/themes/loader';\n\nconst { default: lazyTheme } = await themes['pierre-dark']();\n```\n\n| Entry | Exports |\n| ---------------------------------- | -------------------------------------------------------- |\n| `@pierre/highlights/themes` | Camel-case named themes, `cssVariables`, and `toCSS()` |\n| `@pierre/highlights/themes/` | One theme as the default export, e.g. `pierre-dark` |\n| `@pierre/highlights/themes/loader` | `themes`, a map from bundled IDs to async module loaders |\n\nPass the resolved object as `theme`; a string ID is not accepted. A\n`ThemeFamily` resolves to its first member. Pass `family.themes[index]` to\nselect another. Theme preparation is cached by object identity; create new\nobjects when changing values.\n\nFor `@pierre/diffs` components, load these objects through\n`registerCustomTheme(name, loader, 'zed')` and select\n`preferredHighlighter: 'highlights'`. See the\n[custom highlighting recipe](../../diffs/references/recipe-custom-highlighting.md)\nfor registration and backend selection.\n\n## Custom themes\n\n```ts\nimport type { Theme } from '@pierre/highlights';\n\nconst theme = {\n name: 'App Dark',\n appearance: 'dark',\n style: {\n 'editor.background': '#101010',\n 'editor.foreground': '#eeeeee',\n syntax: {\n keyword: { color: '#c084fc', font_weight: 700 },\n comment: { color: '#888888', font_style: 'italic' },\n },\n },\n} satisfies Theme;\n```\n\nColors support three-, four-, six-, and eight-digit hex and numeric\n`color(display-p3 ...)` values. Use the CSS-variable mode below for application\nvariables. Syntax scopes such as `keyword.control` inherit from their nearest\nconfigured parent.\n\nTheme types come from `@pierre/highlights`:\n\n| Type | Shape |\n| --------------------- | -------------------------------------------------------------------- |\n| `Theme` | `name`, `appearance`, `style`, and optional `cssVariables: true` |\n| `ThemeFamily` | `themes: readonly Theme[]`, optional `name` and `author` |\n| `ThemeStyle` | Editor colors and `syntax`, plus additional Zed style keys |\n| `ThemeSyntaxSettings` | Optional `color`, `font_style`, and `font_weight` |\n| `ThemePlayer` | Optional collaborator `cursor`, `selection`, and `background` colors |\n| `ThemeOptions` | Exactly one of `theme` or `themes` |\n\nEach `style.syntax` value can be a color string or `ThemeSyntaxSettings`.\n\n## Switch colors with CSS variables\n\n```ts\nimport { codeToHtml } from '@pierre/highlights';\nimport { cssVariables, pierreDark, toCSS } from '@pierre/highlights/themes';\n\nconst cssVariablePrefix = '--code-';\nconst html = new TextDecoder().decode(\n codeToHtml('const answer = 42;', {\n lang: 'ts',\n theme: cssVariables,\n cssVariablePrefix,\n })\n);\nconst stylesheet = `.highlights { ${toCSS(pierreDark, { cssVariablePrefix })} }`;\n```\n\nInclude the stylesheet with the markup. `toCSS(theme, options?)` accepts a\n`Theme` and returns declarations without a selector. Apply them to the code\nblock or an ancestor. Keep its prefix and the highlighting prefix equal; both\ndefault to `--hls-`. Changing declarations updates colors without tokenization.\nThis mode controls colors only and ignores theme font style and weight.\n\n## Multiple themes\n\nAll highlighting and tokenization APIs accept a `themes` map. `defaultColor`\nselects how it renders:\n\n| Value | Result |\n| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- |\n| A theme key | Applies that scheme inline and emits other schemes as custom properties; defaults to `light` and throws if the key is absent |\n| `false` | Emits all schemes as custom properties for CSS to select |\n| `'light-dark()'` | Requires `light` and `dark`; merges colors into CSS `light-dark()` values following the page's `color-scheme` |\n\n```ts\nimport { codeToHtml } from '@pierre/highlights';\nimport { pierreDark, pierreLight } from '@pierre/highlights/themes';\n\nconst html = new TextDecoder().decode(\n codeToHtml('const answer = 42;', {\n lang: 'ts',\n themes: { light: pierreLight, dark: pierreDark },\n defaultColor: false,\n })\n);\n```\n\nInclude CSS to select the emitted properties:\n\n```css\n.highlights {\n color: var(--hls-light);\n background-color: var(--hls-light-bg);\n}\n\n.highlights span {\n color: var(--hls-light);\n font-style: var(--hls-light-font-style, normal);\n font-weight: var(--hls-light-font-weight, normal);\n}\n\n@media (prefers-color-scheme: dark) {\n .highlights {\n color: var(--hls-dark);\n background-color: var(--hls-dark-bg);\n }\n\n .highlights span {\n color: var(--hls-dark);\n font-style: var(--hls-dark-font-style, normal);\n font-weight: var(--hls-dark-font-weight, normal);\n }\n}\n```\n\nFor a custom token renderer, apply each token's complete `htmlStyle` map to its\nspan. With `defaultColor: false`, apply `result.rootStyle` as the container's\ninline style, then use equivalent CSS for that container. With an inline\ndefault, the root style is `background-color:${result.bg};color:${result.fg}`;\nthese fields can include additional declarations. Preserve those declarations\ninstead of treating them as single CSS color values.\n\n## Named CSS palettes\n\nA theme can use `cssVariables: { prefix, defaults }` to map syntax categories to\napplication palette variables while retaining font settings:\n\n```ts\nconst theme = {\n name: 'App palette',\n appearance: 'dark',\n cssVariables: {\n prefix: '--app-',\n defaults: { keyword: '#c084fc' },\n },\n style: {\n syntax: {\n keyword: { color: 'keyword', font_weight: 700 },\n comment: { color: 'muted', font_style: 'italic' },\n },\n },\n} satisfies Theme;\n```\n\nSyntax `color` values are variable suffixes in this mode. Unconfigured syntax\ncategories inherit the `foreground` variable, and defaults become CSS `var()`\nfallbacks. The palette prefix belongs to the theme and is independent of the\nprefix used for multiple theme output. Diffs uses this mode for its portable\n`createCSSVariablesTheme` palette.\n","skills/theme/SKILL.md":"---\nname: theme\ndescription:\n Use when an app needs a Pierre light or dark theme from @pierre/theme for\n Shiki, VS Code, Cursor, or Zed, including soft, vibrant, protanopia,\n deuteranopia, and tritanopia variants.\n---\n\n# `@pierre/theme`\n\nUse `@pierre/theme` for Pierre syntax and editor themes. The package supplies\nten immutable Shiki and VS Code theme objects.\n\nFor Zed-compatible themes used by `@pierre/highlights`, read the\n[highlights skill](../highlights/SKILL.md).\n\n## Install\n\n```bash\npnpm add @pierre/theme\n```\n\n## Select an API reference\n\n| Need | Reference |\n| --------------------------------------- | ---------------------------------------- |\n| List every package entry and export | [API reference](references/api.md) |\n| Compare all themes and select a variant | [Theme variants](references/variants.md) |\n\n## Select a recipe\n\n| Task | Recipe |\n| ----------------------------------- | ------------------------------------------------------- |\n| Load a Pierre theme in Shiki | [Use a theme with Shiki](references/recipe-shiki.md) |\n| Install a Pierre theme in an editor | [Use a theme in an editor](references/recipe-editor.md) |\n\nUse the `theming` skill when the app must switch themes at runtime or follow a\ncolor mode.\n","skills/theme/references/api.md":"# `@pierre/theme` API reference\n\nThis reference lists every public package entry.\n\n## Main entry\n\n| Import | Export | Purpose |\n| --------------- | ------------ | ------------------------------------------- |\n| `@pierre/theme` | `themeNames` | Lists the ten theme names in package order. |\n\n## Theme entries\n\nEach entry has one default export. The export is an immutable Pierre theme\nobject.\n\n| Import | Theme name | Color scheme | Purpose |\n| ---------------------------------------------------- | -------------------------------------- | ------------ | ---------------------------------------------------- |\n| `@pierre/theme/pierre-light` | `pierre-light` | Light | Supplies the standard light theme. |\n| `@pierre/theme/pierre-dark` | `pierre-dark` | Dark | Supplies the standard dark theme. |\n| `@pierre/theme/pierre-light-soft` | `pierre-light-soft` | Light | Supplies the soft light theme. |\n| `@pierre/theme/pierre-dark-soft` | `pierre-dark-soft` | Dark | Supplies the soft dark theme. |\n| `@pierre/theme/pierre-light-vibrant` | `pierre-light-vibrant` | Light | Supplies the Display-P3 light theme. |\n| `@pierre/theme/pierre-dark-vibrant` | `pierre-dark-vibrant` | Dark | Supplies the Display-P3 dark theme. |\n| `@pierre/theme/pierre-light-protanopia-deuteranopia` | `pierre-light-protanopia-deuteranopia` | Light | Supplies the light red-green color-vision variant. |\n| `@pierre/theme/pierre-dark-protanopia-deuteranopia` | `pierre-dark-protanopia-deuteranopia` | Dark | Supplies the dark red-green color-vision variant. |\n| `@pierre/theme/pierre-light-tritanopia` | `pierre-light-tritanopia` | Light | Supplies the light blue-yellow color-vision variant. |\n| `@pierre/theme/pierre-dark-tritanopia` | `pierre-dark-tritanopia` | Dark | Supplies the dark blue-yellow color-vision variant. |\n\n## Raw theme entries\n\n`@pierre/theme/themes/*` exposes each generated JSON file. Replace `*` with a\ntheme file name, including `.json`.\n\n## Theme object\n\nEach default export has these immutable fields:\n\n| Field | Purpose |\n| --------------------- | ---------------------------------------------- |\n| `name` | Provides the stable theme identifier. |\n| `displayName` | Provides the label for a theme selector. |\n| `type` | Identifies the `light` or `dark` color scheme. |\n| `colors` | Maps VS Code workbench color keys to colors. |\n| `tokenColors` | Defines TextMate token styles. |\n| `semanticTokenColors` | Defines semantic token styles. |\n","skills/theme/references/recipe-editor.md":"# Recipe: use a Pierre theme in an editor\n\n## VS Code or Cursor\n\n1. Install the **Pierre Theme** extension from the editor marketplace.\n2. Open the color theme selector.\n3. Select a `Pierre` theme.\n\n## Zed\n\n1. Install the **Pierre** extension from the Zed extension registry.\n2. Open the theme selector.\n3. Select a `Pierre` theme.\n\nThe editor extensions include the standard, soft, protanopia and deuteranopia,\nand tritanopia treatments.\n","skills/theme/references/recipe-shiki.md":"# Recipe: use a Pierre theme with Shiki\n\nInstall the package:\n\n```bash\npnpm add @pierre/theme shiki\n```\n\nImport the theme object and pass it to Shiki:\n\n```ts\nimport pierreDark from '@pierre/theme/pierre-dark';\nimport { codeToHtml } from 'shiki';\n\nconst html = await codeToHtml(source, {\n lang: 'typescript',\n theme: pierreDark,\n});\n```\n\nImport a matching light and dark pair when the app supports both color schemes.\nUse the `theming` skill when the user can change the active theme at runtime.\n","skills/theme/references/variants.md":"# Pierre theme variants\n\nSelect one treatment and use its light and dark entries as a pair.\n\n| Treatment | Light entry | Dark entry | Select it for |\n| --------------------------- | -------------------------------------- | ------------------------------------- | ----------------------------------------- |\n| Standard | `pierre-light` | `pierre-dark` | The default Pierre appearance. |\n| Soft | `pierre-light-soft` | `pierre-dark-soft` | A lower-contrast appearance. |\n| Vibrant | `pierre-light-vibrant` | `pierre-dark-vibrant` | Display-P3 output in Shiki or a web page. |\n| Protanopia and deuteranopia | `pierre-light-protanopia-deuteranopia` | `pierre-dark-protanopia-deuteranopia` | Red-green color-vision support. |\n| Tritanopia | `pierre-light-tritanopia` | `pierre-dark-tritanopia` | Blue-yellow color-vision support. |\n\nThe editor extensions include the eight sRGB themes. The vibrant themes use CSS\nDisplay-P3 color syntax and target web output.\n\nUse the standard pair unless the product specifies another treatment. Use the\nsame treatment for both color schemes.\n","skills/theming/SKILL.md":"---\nname: theming\ndescription:\n Use when an app uses @pierre/theming to list, resolve, select, switch,\n persist, or apply themes, including color modes, theme controllers, React\n state, UI colors, and bundled Pierre or Shiki collections.\n---\n\n# `@pierre/theming`\n\nUse `@pierre/theming` to manage runtime themes. The package separates theme\nmetadata, theme resolution, selected state, and UI color mapping.\n\n## Install\n\n```bash\npnpm add @pierre/theming\n```\n\nInstall optional peer dependencies only for the selected entry. The React entry\nneeds `react`. The themes entry needs `@pierre/theme`, `@shikijs/themes`, and\n`shiki`.\n\n## Select an API reference\n\n| Need | Reference |\n| -------------------------------------------------------------- | -------------------------------------------- |\n| Create a collection, catalog, descriptor, or bundled theme set | [Collections API](references/collections.md) |\n| Register, load, seed, or cache theme objects | [Resolver API](references/resolver.md) |\n| Track the color mode and selected light and dark themes | [Controller API](references/controller.md) |\n| Normalize workbench colors or derive colors | [Colors API](references/colors.md) |\n| Read controller state in React | [React API](references/react.md) |\n\n## Select a controller recipe\n\n| Situation | Recipe |\n| ---------------------------------------------------------------------------- | --------------------------------------------------------------------- |\n| One app or page shares one color mode and one light/dark selection | [Use one controller](references/recipe-one-controller.md) |\n| Independent areas need separate selections or separate controller lifecycles | [Use multiple controllers](references/recipe-multiple-controllers.md) |\n\nUse one controller by default. Use multiple controllers only when the theme\nstate must differ between areas.\n\n## Select a framework recipe\n\n| Host | Recipe |\n| --------------------------------------- | ------------------------------------------------------ |\n| Vanilla JavaScript or another framework | [Use vanilla JavaScript](references/recipe-vanilla.md) |\n| React | [Use React](references/recipe-react.md) |\n","skills/theming/references/collections.md":"# Collections API\n\nThis reference covers collection APIs from `@pierre/theming` and all exports\nfrom `@pierre/theming/themes`.\n\n## `@pierre/theming` exports\n\n| Export | Kind | Purpose |\n| --------------------------- | -------- | ------------------------------------------------------------------ |\n| `createThemeCollection` | Function | Creates an immutable ordered set of theme descriptors. |\n| `ThemeCollection` | Type | Defines collection queries, transforms, and resolver registration. |\n| `ThemeCollectionComparator` | Type | Compares two descriptors for `orderBy`. |\n| `ThemeCollectionEntry` | Type | Accepts one descriptor or collection source. |\n| `ThemeCollectionFilter` | Type | Filters by `collection` and `colorScheme`. |\n| `ThemeCollectionInput` | Type | Accepts one entry or an iterable of entries. |\n| `ThemeCollectionSource` | Type | Defines an object that returns theme descriptors. |\n| `ThemeDescriptor` | Type | Describes one named theme and its lazy loader. |\n| `createThemeCatalog` | Function | Creates a collection with default light and dark theme names. |\n| `ThemeCatalog` | Type | Adds default theme names to `ThemeCollection`. |\n\n## `ThemeDescriptor` fields\n\n| Field | Purpose |\n| ------------- | --------------------------------------- |\n| `name` | Stores the stable theme identifier. |\n| `load` | Loads the theme object. |\n| `colorScheme` | Labels the descriptor as light or dark. |\n| `collection` | Groups related themes. |\n| `displayName` | Supplies a user-facing label. |\n\n## `ThemeCollection` methods\n\n| Method | Purpose |\n| ------------------------ | ---------------------------------------------------- |\n| `getTheme(name)` | Gets one descriptor by name. |\n| `getThemes(filter?)` | Lists descriptors that match an optional filter. |\n| `getThemeNames(filter?)` | Lists names that match an optional filter. |\n| `hasTheme(name)` | Tests whether the collection has a name. |\n| `orderBy(compare)` | Returns a new collection in comparator order. |\n| `pick(names)` | Returns a new collection in the supplied name order. |\n| `registerInto(resolver)` | Adds every descriptor loader to a resolver. |\n\n## `ThemeCatalog` fields\n\n| Field | Purpose |\n| ----------------------- | ------------------------------ |\n| `defaultLightThemeName` | Names the initial light theme. |\n| `defaultDarkThemeName` | Names the initial dark theme. |\n\n## `@pierre/theming/themes` exports\n\n| Export | Kind | Purpose |\n| -------------------- | -------- | ----------------------------------------------------------------------------- |\n| `themes` | Value | Combines the Pierre and Shiki collections in stable order. |\n| `pierreThemes` | Value | Provides lazy descriptors for the ten Pierre themes. |\n| `shikiThemes` | Value | Provides lazy descriptors for the bundled Shiki themes. |\n| `createTheme` | Function | Creates a descriptor whose loader normalizes a raw Shiki or VS Code theme. |\n| `CreateThemeOptions` | Type | Defines the name, loader, and optional descriptor metadata for `createTheme`. |\n\nUse `createTheme` for a raw Shiki or VS Code theme. Use a `ThemeDescriptor`\ndirectly when the loader already returns a compatible `ThemeLike` object.\n","skills/theming/references/colors.md":"# Colors API\n\nThis reference covers every export from `@pierre/theming/color`.\n\n## Exports\n\n| Export | Kind | Purpose |\n| ---------------------- | -------- | -------------------------------------------------------------- |\n| `normalizeThemeColors` | Function | Resolves the UI color fallback chains in a `ThemeLike` object. |\n| `colorUtils` | Object | Groups pure color checks and transforms. |\n\n`normalizeThemeColors(theme)` returns a memoized `ThemeLike` object. Use its\n`colors` map for the UI around syntax-highlighted code.\n\n## `colorUtils` methods\n\n| Method | Purpose |\n| ---------------------------------------------------- | -------------------------------------------------------------- |\n| `relativeLuminance(color)` | Calculates WCAG luminance for a hex color. |\n| `contrastRatio(a, b)` | Calculates the contrast ratio between two luminance values. |\n| `compositeOverBg(foreground, background?)` | Flattens a translucent hex color over a background. |\n| `isFullyTransparent(color?)` | Tests whether a hex color has zero alpha. |\n| `isDarkSurface(background?, foregroundHint?)` | Classifies a surface as dark or light. |\n| `surfacesMatch(a?, b?)` | Tests whether two hex surfaces produce the same visible color. |\n| `hoverWouldEraseText(hover, background, foreground)` | Tests whether a hover surface removes text contrast. |\n| `pickReadableForeground(background, candidates)` | Selects the candidate with the best readable contrast. |\n| `deriveMutedFg(foreground, background)` | Derives a muted foreground with readable contrast. |\n\nThe color methods measure hex colors. A method returns its documented empty\nresult when it cannot measure another CSS color format.\n","skills/theming/references/controller.md":"# Controller API\n\nThis reference covers controller and shared theme types from `@pierre/theming`.\n\n## Exports\n\n| Export | Kind | Purpose |\n| ----------------------------- | -------- | ------------------------------------------------------------------ |\n| `createThemeController` | Function | Creates state for a color mode and selected light and dark themes. |\n| `ThemeController` | Type | Defines controller state, mutations, subscription, and cleanup. |\n| `ThemeControllerOptions` | Type | Selects a catalog or resolver and configures initial state. |\n| `ThemeControllerState` | Type | Describes the current selection and resolved theme. |\n| `PendingThemeResolution` | Type | Identifies the active theme load. |\n| `ThemeResolutionError` | Type | Describes a failed active theme load. |\n| `ThemeResolutionErrorContext` | Type | Identifies the name and scheme for a failed load callback. |\n| `ThemePersistence` | Type | Defines custom `load` and `save` methods. |\n| `ThemeSelection` | Type | Describes the persisted mode and theme names. |\n| `ColorMode` | Type | Accepts `light`, `dark`, or `system`. |\n| `ColorScheme` | Type | Accepts concrete `light` or `dark`. |\n| `ThemeLike` | Type | Defines the shared resolved-theme shape. |\n\n## `ThemeControllerOptions` fields\n\n| Field | Purpose |\n| ----------------------- | ------------------------------------------------------------------- |\n| `catalog` | Supplies descriptors and catalog default names. |\n| `resolver` | Supplies an existing resolver or shares one with other controllers. |\n| `defaultLightThemeName` | Overrides the initial light theme name. |\n| `defaultDarkThemeName` | Overrides the initial dark theme name. |\n| `defaultMode` | Sets the initial color mode. |\n| `storageKey` | Stores the selection in browser local storage. |\n| `persistence` | Supplies custom selection storage. |\n| `preloadInactive` | Resolves the inactive color-scheme theme too. |\n| `onResolutionError` | Receives an active theme load error. |\n\nPass a `catalog`, a `resolver`, or a catalog with a shared resolver.\n\n## `ThemeController` members\n\n| Member | Purpose |\n| ------------------------------------- | ---------------------------------------------------------------- |\n| `resolver` | Exposes the controller's resolver. |\n| `getState()` | Returns the current immutable state object. |\n| `setColorMode(mode)` | Selects light, dark, or system mode. |\n| `setThemeNameForScheme(scheme, name)` | Selects the theme for one color scheme. |\n| `subscribe(listener)` | Subscribes to state changes and returns an unsubscribe function. |\n| `destroy()` | Removes the system color-scheme listener. |\n\n## `ThemeControllerState` fields\n\n| Field | Purpose |\n| ------------------------ | -------------------------------------------------- |\n| `lightThemeName` | Stores the selected light theme name. |\n| `darkThemeName` | Stores the selected dark theme name. |\n| `mode` | Stores the selected color mode. |\n| `resolvedColorScheme` | Provides the active concrete light or dark scheme. |\n| `resolvedTheme` | Provides the active resolved theme object. |\n| `pendingThemeResolution` | Identifies an active theme load. |\n| `resolutionError` | Describes the latest active load failure. |\n","skills/theming/references/react.md":"# React API\n\nThis reference lists every export from `@pierre/theming/react`.\n\n| Export | Kind | Purpose |\n| -------------------- | ---- | ------------------------------------------------------------------------- |\n| `useThemeController` | Hook | Subscribes to a `ThemeController` and returns its `ThemeControllerState`. |\n\nThe hook uses the controller state for both client and server snapshots. Create\nthe controller outside the component that reads it.\n","skills/theming/references/recipe-multiple-controllers.md":"# Recipe: use multiple theme controllers\n\nUse multiple controllers when independent areas need different modes,\nselections, storage, or lifecycles. Share one resolver when those areas use the\nsame theme loaders and cache.\n\n```ts\nimport {\n createThemeCatalog,\n createThemeController,\n createThemeResolver,\n} from '@pierre/theming';\nimport { themes } from '@pierre/theming/themes';\n\nconst catalog = createThemeCatalog({\n themes,\n defaultLightThemeName: 'pierre-light',\n defaultDarkThemeName: 'pierre-dark',\n});\n\nconst resolver = createThemeResolver();\n\nexport const workspaceTheme = createThemeController({\n catalog,\n resolver,\n storageKey: 'workspace-theme',\n});\n\nexport const previewTheme = createThemeController({\n catalog,\n resolver,\n defaultMode: 'light',\n storageKey: 'preview-theme',\n});\n```\n\nSubscribe each area to its own controller. Call `destroy()` on each controller\nwhen its area is removed. Use distinct storage keys when selections must remain\nindependent.\n","skills/theming/references/recipe-one-controller.md":"# Recipe: use one theme controller\n\nUse one controller when the app shares one color mode and one light/dark theme\nselection.\n\nCreate the catalog and controller in one module:\n\n```ts\nimport { createThemeCatalog, createThemeController } from '@pierre/theming';\nimport { themes } from '@pierre/theming/themes';\n\nexport const themeCatalog = createThemeCatalog({\n themes,\n defaultLightThemeName: 'pierre-light',\n defaultDarkThemeName: 'pierre-dark',\n});\n\nexport const themeController = createThemeController({\n catalog: themeCatalog,\n defaultMode: 'system',\n storageKey: 'app-theme',\n});\n```\n\nImport the same controller wherever the app reads or changes theme state. Call\n`destroy()` when the application tears down the controller module.\n","skills/theming/references/recipe-react.md":"# Recipe: use a theme controller in React\n\nCreate the controller in a module. Read it with `useThemeController`:\n\n```tsx\nimport { useEffect } from 'react';\nimport { useThemeController } from '@pierre/theming/react';\n\nimport { themeController } from './theme-controller';\n\nexport function ThemeControls() {\n const state = useThemeController(themeController);\n\n useEffect(() => {\n document.documentElement.dataset.colorScheme = state.resolvedColorScheme;\n }, [state.resolvedColorScheme]);\n\n return (\n \n themeController.setColorMode(\n state.resolvedColorScheme === 'dark' ? 'light' : 'dark'\n )\n }\n >\n Use {state.resolvedColorScheme === 'dark' ? 'light' : 'dark'} mode\n \n );\n}\n```\n\nPass `state.resolvedTheme` to code or tree surfaces. Use `normalizeThemeColors`\nwhen a React component needs workbench UI colors.\n","skills/theming/references/recipe-vanilla.md":"# Recipe: use a theme controller in vanilla JavaScript\n\nCreate a controller with the one-controller or multiple-controller recipe. Apply\neach state change to the document:\n\n```ts\nimport { normalizeThemeColors } from '@pierre/theming/color';\nimport { themeController } from './theme-controller';\n\nfunction applyTheme() {\n const state = themeController.getState();\n document.documentElement.dataset.colorScheme = state.resolvedColorScheme;\n\n if (state.resolvedTheme == null) return;\n const { colors } = normalizeThemeColors(state.resolvedTheme);\n document.documentElement.style.setProperty(\n '--app-background',\n colors?.['editor.background'] ?? state.resolvedTheme.bg ?? ''\n );\n document.documentElement.style.setProperty(\n '--app-foreground',\n colors?.['editor.foreground'] ?? state.resolvedTheme.fg ?? ''\n );\n}\n\napplyTheme();\nconst unsubscribe = themeController.subscribe(applyTheme);\n```\n\nCall `themeController.setColorMode(mode)` from a mode control. Call\n`setThemeNameForScheme(scheme, name)` from a theme selector. Call\n`unsubscribe()` when the host no longer needs updates.\n","skills/theming/references/resolver.md":"# Resolver API\n\nThis reference covers the resolver exports from `@pierre/theming`.\n\n## Exports\n\n| Export | Kind | Purpose |\n| ------------------------ | -------- | ------------------------------------------------------------- |\n| `createThemeResolver` | Function | Creates an isolated loader registry and resolved-theme cache. |\n| `ThemeResolver` | Type | Defines the resolver methods. |\n| `ThemeLoader` | Type | Defines an asynchronous theme loader. |\n| `DuplicateThemeError` | Class | Reports a second registration for the same name. |\n| `UnregisteredThemeError` | Class | Reports a resolve request for a name with no loader. |\n| `UnresolvedThemeError` | Class | Reports a synchronous batch read with an unresolved name. |\n\n## `ThemeResolver` methods\n\n| Method | Purpose |\n| ------------------------------------- | -------------------------------------------------------- |\n| `registerTheme(name, loader)` | Registers one loader. |\n| `registerThemeIfAbsent(name, loader)` | Registers one loader only when the name is free. |\n| `hasRegisteredTheme(name)` | Tests whether a loader exists. |\n| `resolveTheme(name)` | Loads and caches one theme. |\n| `resolveThemes(names)` | Loads and caches themes in input order. |\n| `getResolvedTheme(name)` | Reads one cached theme or returns `undefined`. |\n| `getResolvedThemes(names)` | Reads cached themes in input order. |\n| `getResolvedOrResolveTheme(name)` | Returns a cached theme or starts its load. |\n| `hasResolvedTheme(name)` | Tests whether one cached theme exists. |\n| `hasResolvedThemes(names)` | Tests whether all named themes exist in the cache. |\n| `seedResolvedTheme(name, theme)` | Adds one resolved object without a loader. |\n| `seedResolvedThemes(entries)` | Adds several resolved objects without loaders. |\n| `clearResolvedThemes()` | Clears cached themes and active loads but keeps loaders. |\n\nEach loader returns a `ThemeLike` object or a module object with that value on\n`default`.\n\n## Fallback loading and normalization\n\n`createThemeResolver(options?)` accepts `ThemeResolverOptions`:\n\n```ts\nconst resolver = createThemeResolver({\n fallbackLoader: async (name) => {\n const loader = bundledLoaders[name];\n return loader === undefined ? undefined : loader();\n },\n normalizeTheme: (theme, name) => ({ ...theme, name }),\n});\n```\n\nExplicit registrations take precedence over `fallbackLoader`. A fallback may\nreturn a theme, a `{ default: theme }` module, or `undefined` for an unknown\nname. `normalizeTheme(theme, name)` can be synchronous or asynchronous and runs\nbefore successful loads enter the cache. Seeded values are already normalized.\nConcurrent calls share fallback loading and normalization; rejected loads can be\nretried. Clearing caches prevents an earlier in-flight load from repopulating\nthem. The core resolver still imports no backend or bundled theme data.\n","skills/trees/SKILL.md":"","skills/trees/references/api-core.md":"# Core API\n\nThis reference lists every export from `@pierre/trees` and every public\n`FileTree` member.\n\n## Contents\n\n- [Runtime values](#runtime-values)\n- [`FileTree` members](#filetree-members)\n- [Configuration and state types](#configuration-and-state-types)\n- [Mutation types](#mutation-types)\n- [Interaction types](#interaction-types)\n- [Presentation types](#presentation-types)\n- [Constants](#constants)\n\n## Runtime values\n\n| Export | Kind | Purpose |\n| ------------------------------- | -------- | ----------------------------------------------------------------- |\n| `FileTree` | Class | Owns the tree model, renders it, and exposes path-based controls. |\n| `prepareFileTreeInput` | Function | Prepares and optionally sorts a path list for reuse. |\n| `preparePresortedFileTreeInput` | Function | Prepares a path list that already has final order. |\n| `preloadFileTree` | Function | Creates server-rendered tree markup and hydration data. |\n| `serializeFileTreeSsrPayload` | Function | Joins an SSR payload into one host markup string. |\n| `themeToTreeStyles` | Function | Maps a resolved theme to tree host CSS properties. |\n| `getBuiltInSpriteSheet` | Function | Gets the SVG sprite for a built-in icon set. |\n| `createFileTreeIconResolver` | Function | Creates an icon resolver from an icon configuration. |\n\n## `FileTree` members\n\n| Member | Purpose |\n| -------------------------------- | ----------------------------------------------------------- |\n| `new FileTree(options)` | Creates a model from paths or prepared input. |\n| `FileTree.LoadedCustomComponent` | Reports whether the file-tree custom element module loaded. |\n| `render(props)` | Mounts the tree into a wrapper or host element. |\n| `hydrate(props)` | Attaches the model to preloaded host markup. |\n| `unmount()` | Removes the mounted view and keeps the model. |\n| `cleanUp()` | Removes the view and destroys model resources. |\n| `getFileTreeContainer()` | Gets the mounted host element. |\n| `getItem(path)` | Gets a path handle or `null`. |\n| `getFocusedItem()` | Gets the focused item handle or `null`. |\n| `getFocusedPath()` | Gets the focused path or `null`. |\n| `getSelectedPaths()` | Gets the selected paths. |\n| `getComposition()` | Gets the current header and context-menu configuration. |\n| `getItemHeight()` | Gets the resolved row height. |\n| `getDensityFactor()` | Gets the resolved density factor. |\n| `subscribe(listener)` | Subscribes to model changes. |\n| `focusPath(path)` | Focuses a path. |\n| `focusNearestPath(path)` | Focuses and returns the nearest available path. |\n| `scrollToPath(path, options?)` | Scrolls a path into view. |\n| `add(path)` | Adds one path. |\n| `remove(path, options?)` | Removes one path. |\n| `move(from, to, options?)` | Moves one path. |\n| `batch(operations)` | Applies several path mutations together. |\n| `resetPaths(paths, options?)` | Replaces the full path set. |\n| `onMutation(type, handler)` | Subscribes to mutation events. |\n| `setSearch(value)` | Sets or clears the search query. |\n| `openSearch(initialValue?)` | Opens the search session. |\n| `closeSearch()` | Closes the search session. |\n| `isSearchOpen()` | Tests whether search is open. |\n| `getSearchValue()` | Gets the search query. |\n| `getSearchMatchingPaths()` | Gets paths that match the query. |\n| `focusNextSearchMatch()` | Focuses the next search match. |\n| `focusPreviousSearchMatch()` | Focuses the previous search match. |\n| `startRenaming(path?, options?)` | Starts inline rename and reports whether it started. |\n| `setGitStatus(status?)` | Replaces all git status entries. |\n| `applyGitStatusPatch(patch)` | Applies a partial git status update. |\n| `setIcons(icons?)` | Replaces the icon configuration. |\n| `setComposition(composition?)` | Replaces header and context-menu configuration. |\n\n## Configuration and state types\n\n| Export | Purpose |\n| -------------------------- | --------------------------------------------------------------- |\n| `FileTreeOptions` | Defines input, behavior, rendering, and presentation options. |\n| `FileTreePreparedInput` | Holds a reusable prepared path list. |\n| `FileTreeInitialExpansion` | Selects closed, open, or depth-based initial expansion. |\n| `FileTreeSortComparator` | Compares two path entries. |\n| `FileTreeSortEntry` | Describes one path for a sort comparator. |\n| `FileTreeRenderOptions` | Configures row height, row count, overscan, and sticky folders. |\n| `FileTreeRenderProps` | Selects the wrapper or existing host for `render`. |\n| `FileTreeHydrationProps` | Selects the host for `hydrate`. |\n| `FileTreeVisibleRow` | Describes one visible tree row. |\n| `FileTreeItemHandle` | Represents a file or directory item. |\n| `FileTreeFileHandle` | Controls one file item. |\n| `FileTreeDirectoryHandle` | Controls one directory item and its expansion. |\n| `FileTreeListener` | Defines a model subscription callback. |\n| `FileTreeSsrPayload` | Holds the host and shadow markup for server output. |\n\n## Mutation types\n\n| Export | Purpose |\n| ----------------------------------- | -------------------------------------------------------------- |\n| `FileTreeMutationHandle` | Defines the public path mutation methods. |\n| `FileTreeBatchOperation` | Describes one add, remove, or move in a batch. |\n| `FileTreeCollisionStrategy` | Selects error, replace, or skip behavior for a move collision. |\n| `FileTreeMoveOptions` | Configures move collision behavior. |\n| `FileTreeRemoveOptions` | Configures recursive removal. |\n| `FileTreeResetOptions` | Configures a path reset and optional prepared input. |\n| `FileTreeResetPreparedOptions` | Configures a reset that uses prepared input. |\n| `FileTreeMutationEvent` | Represents any mutation event. |\n| `FileTreeMutationSemanticEvent` | Represents an add, remove, move, or reset event. |\n| `FileTreeMutationEventType` | Names a mutation operation. |\n| `FileTreeMutationEventForType` | Selects the event shape for an operation name. |\n| `FileTreeMutationEventInvalidation` | Describes the state invalidation from a mutation. |\n| `FileTreeAddEvent` | Describes one add result. |\n| `FileTreeRemoveEvent` | Describes one remove result. |\n| `FileTreeMoveEvent` | Describes one move result. |\n| `FileTreeResetEvent` | Describes one reset result. |\n| `FileTreeBatchEvent` | Describes one batch result. |\n\n## Interaction types\n\n| Export | Purpose |\n| --------------------------------- | -------------------------------------------------- |\n| `FileTreeSelectionChangeListener` | Receives the selected path list. |\n| `FileTreeSearchChangeListener` | Receives the current search query. |\n| `FileTreeSearchSessionHandle` | Defines search session methods. |\n| `FileTreeSearchMode` | Selects how nonmatching rows appear. |\n| `FileTreeSearchBlurBehavior` | Selects search behavior after focus leaves. |\n| `FileTreeScrollOffset` | Selects top, center, or nearest scroll alignment. |\n| `FileTreeScrollToPathOptions` | Configures focus and alignment for `scrollToPath`. |\n| `FileTreeDragAndDropConfig` | Configures drag rules and completion callbacks. |\n| `FileTreeDropTarget` | Describes the current drop target. |\n| `FileTreeDropContext` | Describes dragged paths and their target. |\n| `FileTreeDropResult` | Describes the completed move or batch operation. |\n| `FileTreeRenamingConfig` | Configures rename rules and callbacks. |\n| `FileTreeRenamingItem` | Describes the item offered to a rename rule. |\n| `FileTreeRenameEvent` | Describes a completed rename. |\n\n## Presentation types\n\n| Export | Purpose |\n| ---------------------------------- | ----------------------------------------------------------- |\n| `FileTreeCompositionOptions` | Configures header and context-menu composition. |\n| `FileTreeHeaderCompositionOptions` | Supplies header HTML or a header renderer. |\n| `ContextMenuItem` | Describes the file or directory for a context menu. |\n| `ContextMenuOpenContext` | Supplies menu position, close, and focus controls. |\n| `ContextMenuAnchorRect` | Describes the menu anchor rectangle. |\n| `ContextMenuTriggerMode` | Selects right-click, button, or both triggers. |\n| `ContextMenuButtonVisibility` | Selects when the row menu button appears. |\n| `FileTreeRowDecoration` | Describes text or icon content in the decoration lane. |\n| `FileTreeRowDecorationContext` | Supplies the item and visible row to a decoration renderer. |\n| `FileTreeRowDecorationRenderer` | Produces one row decoration. |\n| `GitStatus` | Names a supported git status. |\n| `GitStatusEntry` | Assigns a git status to one path. |\n| `FileTreeGitStatusPatch` | Adds, changes, or removes git status entries. |\n| `FileTreeBuiltInIconSet` | Names a built-in icon set. |\n| `FileTreeIconConfig` | Configures built-in and custom icon rules. |\n| `FileTreeIcons` | Accepts an icon set name or icon configuration. |\n| `RemappedIcon` | Names or defines a replacement SVG symbol. |\n| `FileTreeDensity` | Accepts a density keyword or numeric factor. |\n| `FileTreeDensityKeyword` | Names compact, default, or relaxed density. |\n| `FileTreeDensityPreset` | Holds a density factor and row height. |\n| `TreeThemeInput` | Defines the resolved theme accepted by `themeToTreeStyles`. |\n| `TreeThemeStyles` | Maps tree CSS property names to values. |\n\n## Constants\n\n| Export | Purpose |\n| ---------------------------------------------- | --------------------------------------------------------------- |\n| `FILE_TREE_TAG_NAME` | Provides the `file-tree-container` element name. |\n| `FILE_TREE_STYLE_ATTRIBUTE` | Provides the core style marker attribute. |\n| `FILE_TREE_UNSAFE_CSS_ATTRIBUTE` | Provides the custom style marker attribute. |\n| `FILE_TREE_SCROLLBAR_MEASURE_ATTRIBUTE` | Provides the scrollbar measurement attribute. |\n| `FILE_TREE_SCROLLBAR_GUTTER_STYLE_ATTRIBUTE` | Provides the measured scrollbar style attribute. |\n| `FILE_TREE_SCROLLBAR_GUTTER_MEASURED_PROPERTY` | Provides the measured scrollbar CSS property. |\n| `FILE_TREE_DEFAULT_ITEM_HEIGHT` | Provides the default row height. |\n| `FILE_TREE_DENSITY_PRESETS` | Maps each density keyword to its preset. |\n| `FLATTENED_PREFIX` | Provides the identifier prefix for a flattened directory chain. |\n| `HEADER_SLOT_NAME` | Provides the header slot name. |\n| `CONTEXT_MENU_SLOT_NAME` | Provides the context-menu slot name. |\n| `CONTEXT_MENU_TRIGGER_TYPE` | Provides the context-menu trigger type. |\n","skills/trees/references/api-react.md":"# React API\n\nThis reference lists every export from `@pierre/trees/react`.\n\n| Export | Kind | Purpose |\n| -------------------------- | --------- | ---------------------------------------------------------------------- |\n| `FileTree` | Component | Mounts a `FileTree` model in a React host element. |\n| `FileTreeProps` | Type | Defines the model, header, context menu, preload data, and host props. |\n| `FileTreePreloadedData` | Type | Selects the `id` and `shadowHtml` fields for hydration. |\n| `useFileTree` | Hook | Creates one stable `FileTree` model. |\n| `UseFileTreeResult` | Type | Holds the model returned by `useFileTree`. |\n| `useFileTreeSelection` | Hook | Returns the selected path list and updates with the model. |\n| `useFileTreeSearch` | Hook | Returns search state and search actions. |\n| `FileTreeSearchState` | Type | Defines the search snapshot and actions. |\n| `useFileTreeSelector` | Hook | Subscribes to a selected part of model state. |\n| `FileTreeSelector` | Type | Selects a value from a model. |\n| `FileTreeSelectorEquality` | Type | Compares two selected values. |\n\n`FileTreeProps` extends React host attributes except `children`. Its specific\nfields are:\n\n| Field | Purpose |\n| ------------------- | --------------------------------------------------- |\n| `model` | Supplies the required `FileTree` model. |\n| `header` | Supplies React content for the header slot. |\n| `renderContextMenu` | Produces React content for the active context menu. |\n| `preloadedData` | Supplies server markup for hydration. |\n","skills/trees/references/api-ssr.md":"# SSR API\n\nThis reference lists every export from `@pierre/trees/ssr`.\n\n| Export | Kind | Purpose |\n| ----------------------------- | -------- | --------------------------------------------------------------- |\n| `preloadFileTree` | Function | Renders a tree to a `FileTreeSsrPayload`. |\n| `serializeFileTreeSsrPayload` | Function | Creates declarative or DOM-inserted host markup from a payload. |\n| `FileTreeSsrPayload` | Type | Holds the host start, shadow HTML, host end, and stable ID. |\n\n`preloadFileTree` and `serializeFileTreeSsrPayload` are also available from\n`@pierre/trees`.\n","skills/trees/references/api-web-components.md":"# Web components API\n\nImport `@pierre/trees/web-components` to register the `file-tree-container`\ncustom element. The entry exports these APIs:\n\n| Export | Kind | Purpose |\n| --------------------------- | -------- | ------------------------------------------------------------------------- |\n| `FileTreeContainerLoaded` | Value | Confirms that the registration module ran. |\n| `adoptDeclarativeShadowDom` | Function | Copies a declarative template into an empty shadow root. |\n| `ensureFileTreeStyles` | Function | Installs the core tree stylesheet in a shadow root. |\n| `prepareFileTreeShadowRoot` | Function | Adopts server markup, installs styles, and measures the scrollbar gutter. |\n","skills/trees/references/recipe-interactions.md":"","skills/trees/references/recipe-react.md":"","skills/trees/references/recipe-ssr.md":"","skills/trees/references/recipe-theme.md":"","skills/trees/references/recipe-vanilla.md":""},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# PierreJS Monorepo\n\n## Agent Environment\n\nSet `AGENT=1` at the start of every terminal session so Bun's test runner emits\nAI-friendly output:\n\n```bash\nexport AGENT=1\n```\n\nMost local moon tasks (formatters, benchmarks, worktree management) are\nconfigured with `runInCI: 'always'` so they keep working in CI-marked shells\nlike agent harnesses. Tasks connected to the build graph (dev servers, prod\nserves, e2e variants, publish guards) stay CI-skipped — run those with\n`moonx --ignore-ci-checks`, e.g.\n`moonx docs:dev-diffs --ignore-ci-checks`. For non-moon commands that CI-gate\nthemselves, unset the var: `CI= pnpm publish --dry-run`.\n\n## Toolchain\n\n- Tool versions (bun, pnpm, node, moon, gh) are pinned in `.prototools` and\n managed by [proto](https://moonrepo.dev/docs/proto); run `proto use` if a tool\n is missing or a pin changed. Never install toolchain versions globally; bump\n pins only in `.prototools`.\n- [moon](https://moonrepo.dev/docs) is the task runner; `package.json` scripts\n are npm lifecycle hooks only.\n\n## Core Rules\n\n- Use `pnpm` for install/add/remove/dedupe/package-manager and publishing work.\n Do not use `bun`, `npm`, `yarn`, `npx`, or similar tools for package\n operations unless there is a specific reason.\n- Dependencies use the `catalog` in `pnpm-workspace.yaml`. Never add dependency\n versions directly to package-level `package.json` files unless a published\n package intentionally needs its own range.\n- Run tasks through moon: `moon run :` (or the `moonx` shorthand)\n works from anywhere in the repo. `moonx : -- args` forwards\n arguments. Discover tasks with `moon tasks `.\n- Preserve trailing newlines at the end of files.\n- Setup steps for a fresh clone live in `CONTRIBUTING.md`.\n\n## Licensing\n\nEvery package in this repo is licensed under Apache 2.0. When adding a new\npackage under `packages/*` or `apps/*`:\n\n- Set `\"license\": \"apache-2.0\"` in its `package.json`.\n- Add an Apache 2.0 `LICENSE.md` at the package root — copy one from an existing\n package (e.g. `packages/trees/LICENSE.md`).\n\nVendored third-party code keeps its original license; record that attribution in\na `NOTICE.md` next to the package rather than changing its LICENSE.\n\n`moon run root:check-licenses` enforces both requirements and runs in CI on\nevery PR.\n\n## Skills\n\nDomain-specific context and conventions live in `.agents/skills/`. Before\nstarting any task:\n\n1. List `.agents/skills/*/SKILL.md`\n2. Read only each skill's frontmatter description to identify relevant skills\n3. Read only the full `SKILL.md` files relevant to your task\n\nDo not load skills that are not relevant to the task.\n\n## Agent Artifacts\n\nWrite agent-only planning and scratch artifacts under `.agents/ignore/` by\ndefault:\n\n- Plans: `.agents/ignore/plans/YYYY-MM-DD-.md`\n- Specs: `.agents/ignore/specs/YYYY-MM-DD-.md`\n\n`.agents/ignore/` is gitignored. Do not put source files, tests, or committed\ndocumentation there.\n\n## Verification Baseline\n\nAfter code changes, verification is not complete until you have run these from\nanywhere in the repo:\n\n```bash\nmoon run root:format root:lint\n```\n\nAlso run the affected typecheck and focused tests for the changed area, e.g.\n`moonx :typecheck` and `moonx :test` (or\n`moonx :typecheck --affected`). For docs-only or AGENTS/skill-only changes,\nformatting and linting are sufficient unless the edit touches executable code or\npackage config.\n\n## Code Readability\n\n- When adding non-trivial helpers, prefer a short comment directly above the\n function explaining what the helper does and why it exists.\n- Write comments for readers new to the codepath. Avoid vague shorthand like\n \"snapshot\" unless you immediately explain what data is captured or derived.\n- Prefer function-level comments over many inline comments. Use inline comments\n only when a specific step is still non-obvious.\n- Keep comments concrete and behavior-focused.\n","isInternal":false,"tokens":988,"sizeBytes":3957},{"name":"CLAUDE.md","path":"CLAUDE.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/CLAUDE.md","title":"Claude Agent Guidelines & System Prompt","category":"claude-rule","format":"markdown","content":"@AGENTS.md\n","isInternal":false,"tokens":5,"sizeBytes":11},{"name":"SKILL.md","path":".agents/skills/browser-automation/SKILL.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/.agents/skills/browser-automation/SKILL.md","title":"browser-automation","category":"anthropic-skill","format":"markdown","content":"---\nname: browser-automation\ndescription:\n Use when opening, inspecting, clicking, filling, snapshotting, or otherwise\n automating web pages for this repo, including local dev servers and\n browser-based verification.\n---\n\n# Browser Automation\n\nUse `agent-browser` for web automation in this repo. Run:\n\n```bash\nagent-browser --help\n```\n\nCore workflow:\n\n```bash\nagent-browser open \nagent-browser snapshot -i\nagent-browser click @e1\nagent-browser fill @e2 \"text\"\n```\n\nRe-run `agent-browser snapshot -i` after page changes so element refs stay\ncurrent.\n\nUse browser automation for behavior that needs a rendered page, real DOM state,\nor interactive verification. Prefer focused Bun tests for pure logic and\nnon-browser integration behavior.\n","frontmatter":{"name":"browser-automation","description":"Use when opening, inspecting, clicking, filling, snapshotting, or otherwise automating web pages for this repo, including local dev servers and browser-based verification."},"isInternal":false,"tokens":164,"sizeBytes":746},{"name":"SKILL.md","path":".agents/skills/testing-and-verification/SKILL.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/.agents/skills/testing-and-verification/SKILL.md","title":"testing-and-verification","category":"anthropic-skill","format":"markdown","content":"---\nname: testing-and-verification\ndescription:\n Use when adding or running tests, checking snapshots, choosing between Bun\n tests and Playwright, running lint/format/typecheck, or deciding the\n verification scope for a change.\n---\n\n# Testing and Verification\n\n## Baseline Commands\n\nAfter code changes, run the required baseline (moon tasks run from anywhere in\nthe repo, including CI-marked agent shells):\n\n```bash\nmoon run root:format root:lint\n```\n\nUseful check/fix pairs on the root project:\n\n```bash\nmoon run root:format-check\nmoon run root:format\nmoon run root:lint\nmoon run root:lint-fix\nmoon run root:lint-css\nmoon run root:lint-css-fix\n```\n\nFor code changes, also run the relevant typecheck (moon builds workspace\ndependencies first automatically):\n\n```bash\nmoonx :typecheck\n# or, scoped to what actually changed:\nmoonx :typecheck --affected\n```\n\nThe React Compiler lint rules (`react/*` in `.oxlintrc.json`) assume React.\n`packages/trees/src/render/**/*.tsx` and\n`packages/trees/src/components/**/*.tsx` are Preact, so an `overrides` entry\nthere turns `react/refs` off for those globs. Put new Preact components under\nthose directories instead of adding per-file `oxlint-disable` headers.\n\n## Unit and Integration Tests\n\nUse Bun's built-in test runner. Tests usually live in a `test/` folder inside\neach package and use `describe`, `test`, and `expect` from `bun:test`.\n\nPrefer unit or integration tests by default:\n\n```bash\nmoonx diffs:test\nmoonx trees:test\n```\n\n`moon run :test` runs every project's suite. Tests import workspace dependencies\nthrough their built dist, so moon builds those first; running `bun test`\ndirectly inside a package also works when dist is fresh.\n\n## Snapshots\n\nBun supports `toMatchSnapshot()`. Avoid new snapshot coverage unless it is\nshallow and narrowly scoped to the exact behavior under test.\n\nUpdate snapshots from the package directory:\n\n```bash\nbun test -u\n```\n\n## Browser and E2E Tests\n\nAdd Playwright/browser E2E tests only when behavior cannot be validated without\na real browser engine. Good candidates include computed style checks, shadow DOM\nboundaries, and browser-only rendering behavior.\n\nKeep E2E coverage small and high-value:\n\n```bash\nmoonx trees:coverage\nmoonx trees:test-e2e\nmoonx path-store:test-demo\nmoonx docs:test-e2e\n```\n\nIf E2E fixtures or dev servers are started in a worktree, follow the cleanup\ncontract from the `worktrees-and-dev-servers` skill.\n","frontmatter":{"name":"testing-and-verification","description":"Use when adding or running tests, checking snapshots, choosing between Bun tests and Playwright, running lint/format/typecheck, or deciding the verification scope for a change."},"isInternal":false,"tokens":579,"sizeBytes":2431},{"name":"SKILL.md","path":".agents/skills/tooling-and-dependencies/SKILL.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/.agents/skills/tooling-and-dependencies/SKILL.md","title":"tooling-and-dependencies","category":"anthropic-skill","format":"markdown","content":"---\nname: tooling-and-dependencies\ndescription:\n Use when running repo scripts, adding or changing dependencies, editing\n package.json files, installing packages, publishing packages, or deciding when\n pnpm package operations versus Bun runtime commands should be invoked.\n---\n\n# Tooling and Dependencies\n\n## Toolchain (proto)\n\n- Tool versions (bun, pnpm, node, moon, gh) are pinned in `.prototools` and\n managed by [proto](https://moonrepo.dev/docs/proto); its shims put the pinned\n versions on PATH inside the repo. `proto use` installs everything after a pin\n changes.\n- Bump a tool by editing `.prototools` only — never install tools globally or\n pin versions elsewhere. moon's version is additionally enforced by\n `versionConstraint` in `.moon/workspace.yml` and mirrored as the\n `@moonrepo/cli` catalog entry (for Vercel builders without proto); keep all\n three in sync.\n- CI and local shells resolve the same toolchain: CI installs it with\n `moonrepo/setup-toolchain`, which runs `proto install` against the same\n `.prototools`.\n\n## Package Manager and Runtime\n\n- Use `pnpm` for package operations: install, add, remove, dedupe, lockfile,\n package-runner, and publish work.\n- Do not use `bun`, `npm`, `yarn`, `npx`, or other package runners for package\n operations unless there is a specific documented reason.\n- Bun remains the direct TypeScript runtime and Bun test runner where current\n moon tasks use it. Local scripts may still be `.ts` files without a separate\n compile step.\n\n## Dependency Catalog\n\nThis monorepo uses the `catalog` in `pnpm-workspace.yaml`.\n\n- Never add a version directly to an individual package's `package.json` by\n default.\n- To add a dependency:\n 1. Add the exact version to `pnpm-workspace.yaml` under `catalog`, for example\n `\"new-package\": \"1.2.3\"`.\n 2. Reference it from the package with `\"new-package\": \"catalog:\"`.\n- Do not run `pnpm add ` inside a package directory; it writes direct\n versions and breaks the catalog pattern unless you manually normalize them.\n- Published packages may intentionally use ranges for end-user compatibility.\n `apps/docs` should use catalog versions; published packages such as\n `packages/diffs` may use ranges only when that is intentional.\n\n## Tasks\n\n- All build/dev/test/lint entrypoints are moon tasks; package.json scripts exist\n only for npm lifecycle hooks (`prepublishOnly`). Never add task scripts back\n to a package.json.\n- Tasks are defined in `.moon/tasks/*.yml` (inherited) and each project's\n `moon.yml`. Repo-wide tooling (format, lint, icons, clean) lives on the `root`\n project.\n- Run tasks from anywhere in the repo:\n\n```bash\nmoon run :\nmoonx : # same engine; shorthand for moon exec\nmoonx : -- --flags # forward arguments after --\nmoon run :test # a task across every project that has it\nmoon tasks # discover a project's tasks\n```\n\n`moon run` and `moonx` (an alias binary for `moon exec`) execute the same action\npipeline: identical dependency resolution, caching, and affected support. Use\nthem interchangeably; docs write `moon run` for canonical commands and `moonx`\nin interactive examples. The one practical difference: `moonx`/`moon exec`\nexposes CI-behavior overrides (`--ignore-ci-checks`, `--ci `) that\n`moon run` lacks. `moon ci` is a third thing — the affected-aware orchestrator\nused only by `.github/workflows/ci.yml`; never reach for it locally.\n\nmoon builds dependency projects first (`deps: ['^:build']`), caches outputs, and\nskips tasks whose inputs have not changed. Local-only tasks set explicit options\ninstead of moon presets (presets force `runInCI: skip`, which moon refuses to\nrun in CI-detected shells; agent harnesses export `CI=1`):\n\n- No graph edges at all (formatters, benchmarks, wt, servers spawned by\n playwright): use `runInCI: 'always'` — runnable everywhere, and never in the\n CI pipeline because a task with no deps or dependents is never affected\n through the graph.\n- Connected to the build graph (dev/prod, e2e variants, publish guards): keep\n `runInCI: 'skip'` — `moon ci --include-relations` runs affected\n runInCI-enabled tasks even when unrequested, which would pull them into CI.\n Run them in CI-marked shells with `moonx --ignore-ci-checks` (works\n regardless of the shell's CI env). For non-moon commands that CI-gate\n themselves, unset the var instead: `CI= pnpm publish --dry-run`.\n","frontmatter":{"name":"tooling-and-dependencies","description":"Use when running repo scripts, adding or changing dependencies, editing package.json files, installing packages, publishing packages, or deciding when pnpm package operations versus Bun runtime commands should be invoked."},"isInternal":false,"tokens":1101,"sizeBytes":4495},{"name":"SKILL.md","path":".agents/skills/typescript-monorepo/SKILL.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/.agents/skills/typescript-monorepo/SKILL.md","title":"typescript-monorepo","category":"anthropic-skill","format":"markdown","content":"---\nname: typescript-monorepo\ndescription:\n Use when adding or changing packages/apps, TypeScript configs, workspace\n dependencies, package references, exports, or monorepo project-reference\n relationships.\n---\n\n# TypeScript Monorepo\n\n## TypeScript\n\nUse TypeScript everywhere practical. Compiler settings are intentionally fairly\nstrict.\n\n- Shared compiler options live in `tsconfig.options.json`.\n- Root `tsconfig.json` manages project references across the monorepo.\n- Typechecking uses TypeScript 7's native `tsc` (the successor to the `tsgo`\n preview) and runs through moon: `moonx :typecheck` (moon builds\n workspace dependencies first, since types resolve through each dependency's\n built dist). Next runs the same `tsc` for its build-time check through\n `experimental.useTypeScriptCli`, which is on by default since Next 16.3.\n\n## Project References\n\nWhen adding a new package or app:\n\n- Add it to the root `tsconfig.json` references.\n- Ensure its local `tsconfig.json` follows existing package/app patterns.\n- Give it a `moon.yml` (language, layer, tags, and any project-specific tasks);\n shared tasks come from `.moon/tasks/*.yml` via tags or project language.\n\nWhen one workspace package depends on another:\n\n- Add the dependency as `workspace:*` in the consuming package.\n- Add the dependency to the consuming package's TypeScript `references` block\n when needed for accurate and fast typechecking.\n\n## Workspace Dependencies\n\nUse the `pnpm-workspace.yaml` catalog rules from `tooling-and-dependencies` for\nexternal packages. Use `workspace:*` for internal package dependencies.\n\nIf a package is published, review its `exports`, `typesVersions`, `files`, peer\ndependencies, and its moon `prepublish` task chain before changing public\nentrypoints or dependency ranges.\n","frontmatter":{"name":"typescript-monorepo","description":"Use when adding or changing packages/apps, TypeScript configs, workspace dependencies, package references, exports, or monorepo project-reference relationships."},"isInternal":false,"tokens":395,"sizeBytes":1797},{"name":"SKILL.md","path":".agents/skills/worktrees-and-dev-servers/SKILL.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/.agents/skills/worktrees-and-dev-servers/SKILL.md","title":"worktrees-and-dev-servers","category":"anthropic-skill","format":"markdown","content":"---\nname: worktrees-and-dev-servers\ndescription:\n Use when working with the repo's moonx root:wt worktree helper, Pierre-managed\n worktrees, dev-server port offsets, stale server cleanup, Playwright fixtures,\n or Chrome debug instances. Do not use this as a substitute for host-provided\n workspace isolation.\n---\n\n# Worktrees and Dev Servers\n\nPierre includes a repo-specific `git worktree` helper for local/manual\nparallelization outside host-managed agent workspaces. Managed Pierre worktrees\nlive at:\n\n```text\n~/pierre/pierre-worktrees//\n```\n\nEach managed Pierre worktree owns a port offset so dev servers, E2E fixtures,\nand the Chrome remote-debug instance do not collide. The main clone keeps\nhistorical default ports; linked Pierre worktrees shift ports.\n\nIf you are already inside a Conductor, Codex, Claude, or other host-provided\nworkspace, do not create another worktree unless the user explicitly asks for a\nPierre-managed worktree. Still use this skill when you start repo dev servers or\nE2E fixtures, because the cleanup and port-offset rules apply to those scripts.\n\n## Worktree Commands\n\nThe `wt` suite is defined in `scripts/wt.ts`, exposed as the `root:wt` moon\ntask, and manages only Pierre-managed worktrees:\n\n```bash\nmoonx root:wt -- new # create a worktree, allocate offset, pnpm install\nmoonx root:wt -- rm # kill its processes, remove the worktree\nmoonx root:wt -- clean # kill zombie servers on all managed worktree ports\nmoonx root:wt -- clean # clean one managed worktree\nmoonx root:wt -- ps # show per-worktree port status (LISTEN / -)\nmoonx root:wt -- list # summary of managed + external worktrees\n```\n\nPort-binding moon tasks read the offset from `/.env.worktree` via\ntheir `envFile` option. Before starting, dev tasks run `scripts/run-dev.sh` to\nkill any stale process bound to the target port.\n\n## Cleanup Contract\n\nIf you start dev servers, Playwright fixtures, or Chrome debug instances inside\na worktree, run cleanup before completing your turn:\n\n```bash\nmoonx root:wt -- clean \n```\n\nUse `moonx root:wt -- clean` when you do not know the slug or need to clean\nevery managed worktree. Use `moonx root:wt -- rm ` only when intentionally\ntearing down the worktree itself.\n","frontmatter":{"name":"worktrees-and-dev-servers","description":"Use when working with the repo's moonx root:wt worktree helper, Pierre-managed worktrees, dev-server port offsets, stale server cleanup, Playwright fixtures, or Chrome debug instances. Do not use this as a substitute for host-provided workspace isolation."},"isInternal":false,"tokens":559,"sizeBytes":2292},{"name":"api-core.md","path":"skills/diffs/references/api-core.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/diffs/references/api-core.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Core API\n\nThis reference covers components, parsing, merge conflicts, and file extension\nAPIs from `@pierre/diffs`.\n\n## Contents\n\n- [File components](#file-components)\n- [Virtualized components](#virtualized-components)\n- [`File` members](#file-members)\n- [`FileDiff` members](#filediff-members)\n- [`CodeView` members](#codeview-members)\n- [Parsing and patch APIs](#parsing-and-patch-apis)\n- [Merge conflict APIs](#merge-conflict-apis)\n- [Annotation APIs](#annotation-apis)\n- [File extension APIs](#file-extension-apis)\n\n## File components\n\n| Export | Kind | Purpose |\n| --------------------------------------- | -------- | ------------------------------------------------------------- |\n| `File` | Class | Renders one syntax-highlighted file. |\n| `FileOptions` | Type | Configures file display, interaction, slots, and callbacks. |\n| `FileRenderProps` | Type | Defines file input and a render target. |\n| `FileHydrateProps` | Type | Defines file input and preloaded markup for hydration. |\n| `FileDiff` | Class | Renders a file diff from files or parsed metadata. |\n| `FileDiffOptions` | Type | Configures diff display, interaction, slots, and callbacks. |\n| `FileDiffRenderBaseProps` | Type | Defines shared diff render input. |\n| `FileDiffRenderProps` | Type | Adds files or parsed metadata to diff render input. |\n| `FileDiffHydrationProps` | Type | Defines diff input and preloaded markup for hydration. |\n| `FileDiffType` | Type | Identifies a standard or unresolved diff instance. |\n| `UnresolvedFile` | Class | Renders one file with merge conflict controls. |\n| `UnresolvedFileOptions` | Type | Configures merge conflict display and callbacks. |\n| `UnresolvedFileRenderProps` | Type | Defines merge conflict render input. |\n| `UnresolvedFileHydrationProps` | Type | Defines merge conflict input for hydration. |\n| `MergeConflictActionsTypeOption` | Type | Selects no actions, default actions, or a custom renderer. |\n| `RenderMergeConflictActions` | Type | Defines a vanilla conflict action renderer. |\n| `getUnresolvedDiffHunksRendererOptions` | Function | Converts unresolved-file options to hunk renderer options. |\n| `CodeView` | Class | Renders a virtualized list of files and diffs. |\n| `CodeViewOptions` | Type | Configures list layout, items, slots, selection, and editing. |\n| `CodeViewLineSelection` | Type | Associates a selected range with one item ID. |\n| `CodeViewRenderedFileItem` | Type | Describes one mounted file item. |\n| `CodeViewRenderedDiffItem` | Type | Describes one mounted diff item. |\n| `CodeViewRenderedItem` | Type | Represents a mounted file or diff item. |\n| `CodeViewCoordinator` | Type | Coordinates React slots with the vanilla list. |\n| `CodeViewSlotSnapshot` | Type | Describes mounted items and list header or footer hosts. |\n| `CodeViewScrollListener` | Type | Receives list scroll changes. |\n| `CODE_VIEW_FILE_OPTION_KEYS` | Value | Lists file options that `CodeView` passes to an item. |\n| `CODE_VIEW_DIFF_OPTION_KEYS` | Value | Lists diff options that `CodeView` passes to an item. |\n\n## Virtualized components\n\n| Export | Kind | Purpose |\n| -------------------------------------------------- | ----- | ----------------------------------------------------------- |\n| `Virtualizer` | Class | Tracks a simple viewport and connected render instances. |\n| `VirtualizerConfig` | Type | Configures overscroll, observation margin, and resize logs. |\n| `VirtualizedFile` | Class | Adds simple viewport behavior to `File`. |\n| `VirtualizedFileDiff` | Class | Adds simple viewport behavior to `FileDiff`. |\n| `VIRTUALIZED_FILE_DIFF_LAYOUT_CHECKPOINT_INTERVAL` | Value | Sets the line interval for virtual diff layout checkpoints. |\n\n## `File` members\n\n| Member | Purpose |\n| --------------------------------------------- | ---------------------------------------------------- |\n| `new File(options?, workerManager?)` | Creates one file renderer. |\n| `render(props)` | Renders file contents. |\n| `hydrate(props)` | Attaches to preloaded file markup. |\n| `rerender()` | Renders the current file again. |\n| `setOptions(options)` | Replaces file options. |\n| `setThemeType(themeType)` | Selects system, light, or dark theme mode. |\n| `onThemeChange()` | Applies a changed theme. |\n| `setLineAnnotations(annotations)` | Replaces file annotations. |\n| `setSelectedLines(range, options?)` | Replaces the selected line range. |\n| `setEditorActiveLine(line, options?)` | Marks the editor's active line. |\n| `getHoveredLine()` | Gets the current hovered line. |\n| `getOrCreateLineCache(file?)` | Gets cached source lines. |\n| `attachEditor(editor)` | Attaches an editor and returns a detach function. |\n| `applyDocumentChange(document, annotations?)` | Applies an editor document update. |\n| `updateRenderCache(tokens, themeType)` | Updates highlighted token cache entries. |\n| `primeHighlightCache()` | Preloads the highlighted file result. |\n| `renderPlaceholder(height)` | Renders a fixed-height placeholder. |\n| `virtualizedSetup()` | Prepares the instance for a virtualizer. |\n| `flushManagers()` | Applies deferred interaction and size manager state. |\n| `cleanUp(recycle?)` | Releases rendered resources. |\n\n## `FileDiff` members\n\n`FileDiff` supports the shared `File` update, selection, annotation, editor,\nhydration, placeholder, and cleanup members with diff data.\n\n| Member | Purpose |\n| -------------------------------------------- | ------------------------------------------------ |\n| `new FileDiff(options?, workerManager?)` | Creates one diff renderer. |\n| `render(props)` | Parses or renders diff input. |\n| `hydrate(props)` | Attaches to preloaded diff markup. |\n| `rerender()` | Renders the current diff again. |\n| `setOptions(options)` | Replaces diff options. |\n| `getLineIndex(line, side?)` | Maps a displayed line to row and column indexes. |\n| `handleExpandHunk(index, direction, count?)` | Handles a hunk expansion request. |\n| `expandHunk(index, direction, count?)` | Expands hidden context around one hunk. |\n| `completeEditSession()` | Recomputes diff metadata after an edit session. |\n| `isLineRenderable(line)` | Tests whether an additions line is visible. |\n| `getNearestRenderableLine(line, direction)` | Finds a visible additions line. |\n| `revealLine(line)` | Expands context to show an additions line. |\n| `primeHighlightCache(diff?)` | Preloads the highlighted diff result. |\n\n## `CodeView` members\n\n| Member | Purpose |\n| ---------------------------------------- | -------------------------------------------- |\n| `new CodeView(options?, workerManager?)` | Creates one virtualized list. |\n| `setup(root)` | Attaches the list to its scroll root. |\n| `setItems(items)` | Replaces all items. |\n| `addItem(item)` | Appends one item. |\n| `addItems(items)` | Appends several items. |\n| `getItem(id)` | Gets one item by ID. |\n| `updateItem(item)` | Replaces one item by ID. |\n| `updateItemId(oldId, newId)` | Changes one item ID. |\n| `getEditor(id)` | Gets the active editor for an item. |\n| `scrollTo(target)` | Scrolls to a position, item, line, or range. |\n| `setSelectedLines(selection, options?)` | Sets the selected item and range. |\n| `getSelectedLines()` | Gets the selected item and range. |\n| `clearSelectedLines(options?)` | Clears the selected lines. |\n| `setOptions(options)` | Replaces list options. |\n| `onThemeChange()` | Applies a changed theme to list items. |\n| `render(immediate?)` | Schedules or performs a render. |\n| `getWindowSpecs()` | Gets the current virtual window. |\n| `getContainerElement()` | Gets the scroll content element. |\n| `getHeaderElement()` | Gets the list header host. |\n| `getFooterElement()` | Gets the list footer host. |\n| `getRenderedItems()` | Gets mounted items. |\n| `setSlotCoordinator(coordinator?)` | Sets the external slot coordinator. |\n| `getSlotSnapshot(coordinator)` | Gets the coordinator's mounted slot state. |\n| `subscribeToScroll(listener)` | Subscribes to scroll changes. |\n| `getLocalTopForInstance(instance)` | Gets an instance offset inside the list. |\n| `getTopForItem(id)` | Gets an item offset inside the list. |\n| `instanceChanged(instance, layoutDirty)` | Reports a render instance change. |\n| `reset()` | Clears items and render state. |\n| `cleanUp()` | Releases list resources. |\n\n## Parsing and patch APIs\n\n| Export | Purpose |\n| ---------------------------- | ----------------------------------------------------- |\n| `parseDiffFromFile` | Creates `FileDiffMetadata` from old and new files. |\n| `parsePatchFiles` | Parses a patch string into file diff metadata. |\n| `processPatch` | Parses one patch section. |\n| `processFile` | Converts one parsed patch file to `FileDiffMetadata`. |\n| `getSingularPatch` | Selects one file patch from a patch string. |\n| `trimPatchContext` | Limits unchanged context in patch text. |\n| `hydratePartialDiff` | Adds loaded file contents to partial diff metadata. |\n| `cloneFileDiffMetadata` | Creates a structural copy of diff metadata. |\n| `cleanLastNewline` | Normalizes the final newline for diff input. |\n| `getLineEndingType` | Detects a file's line-ending sequence. |\n| `getTotalLineCountFromHunks` | Counts rendered rows across hunks. |\n| `parseLineType` | Parses one patch line marker and content. |\n| `ParsedLine` | Describes the result from `parseLineType`. |\n\n## Merge conflict APIs\n\n| Export | Purpose |\n| ---------------------- | --------------------------------------------------------------- |\n| `resolveConflict` | Applies one current, incoming, or combined conflict resolution. |\n| `resolveRegion` | Resolves one parsed merge conflict region. |\n| `diffAcceptRejectHunk` | Applies accept or reject behavior to one change hunk. |\n\n## Annotation APIs\n\n| Export | Purpose |\n| ---------------------------- | ---------------------------------------------------------- |\n| `isFileAnnotation` | Tests whether one annotation targets a file line. |\n| `isDiffAnnotation` | Tests whether one annotation targets a diff side and line. |\n| `isFileAnnotationCollection` | Tests whether an array contains file annotations. |\n| `isDiffAnnotationCollection` | Tests whether an array contains diff annotations. |\n\n## File extension APIs\n\n| Export | Purpose |\n| ---------------------------- | ------------------------------------------------ |\n| `getFiletypeFromFileName` | Infers a language from a file name. |\n| `setCustomExtension` | Maps one file name or extension to a language. |\n| `replaceCustomExtensions` | Replaces all custom mappings. |\n| `getCustomExtensionsMap` | Gets a copy of custom mappings. |\n| `getCustomExtensionsVersion` | Gets the mapping revision. |\n| `EXTENSION_TO_FILE_FORMAT` | Maps built-in extensions and names to languages. |\n| `setLanguageOverride` | Assigns a language to parsed diff files. |\n","isInternal":false,"tokens":2728,"sizeBytes":15103},{"name":"api-editor.md","path":"skills/diffs/references/api-editor.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/diffs/references/api-editor.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Editor API\n\nThis reference lists the primary exports from `@pierre/diffs/edit` and the\neditor APIs used by common integrations.\n\n## Exports\n\n| Export | Kind | Purpose |\n| --------------------------- | ----- | -------------------------------------------------------------- |\n| `CaretMetadata` | Type | Supplies the color shared by a remote caret and its highlight. |\n| `Editor` | Class | Adds text editing to a `File` or `FileDiff` instance. |\n| `EditorCaret` | Type | Describes an externally owned caret or highlighted selection. |\n| `EditStateManager` | Value | Manages keyed in-memory edit history and state. |\n| `ClearEditStateOptions` | Type | Selects retained state parts to clear. |\n| `EditState` | Type | Holds one complete live editing session. |\n| `EditorInitialState` | Type | Selects state fields to supply on first attachment. |\n| `EditorChange` | Type | Describes one normalized editor change. |\n| `EditorChangeEvent` | Type | Provides normalized edits and the current document. |\n| `EditorActiveLineOptions` | Type | Configures reveal behavior for an editor active line. |\n| `EditorEditCompleteEvent` | Type | Unites file and diff completion events for editor observation. |\n| `FileEditCompleteEvent` | Type | Describes a completed file edit session. |\n| `FileDiffEditCompleteEvent` | Type | Describes a completed diff edit session. |\n| `EditorCommand` | Type | Names an editor command. |\n| `EditorType` | Type | Selects a `file` or `file-diff` editor surface. |\n| `EditorFactory` | Type | Defines an editor-type-aware editor factory. |\n| `EditorFocusOptions` | Type | Selects a focus target and scroll behavior. |\n| `EditorKeymap` | Type | Defines ordered custom shortcut groups. |\n| `EditorOptions` | Type | Configures history, initial state, behavior, and events. |\n| `EditorShortcut` | Type | Defines one command shortcut. |\n| `EditorSelection` | Type | Adds caret direction to an editor range. |\n| `EditorViewState` | Type | Holds selections and editor-owned viewport offsets. |\n| `EditorViewportState` | Type | Holds horizontal and optional vertical scroll offsets. |\n| `KeyboardKey` | Type | Names a key accepted by an editor shortcut. |\n| `KeyboardModifier` | Type | Names a modifier accepted by an editor shortcut. |\n| `TextDocument` | Class | Stores text, positions, edits, search, and undo history. |\n| `TextDocumentChange` | Type | Describes the lines and characters changed by an edit. |\n| `Position` | Type | Identifies a zero-based line and character. |\n| `Range` | Type | Identifies a start and end position. |\n| `ResolvedTextEdit` | Type | Stores an edit with resolved document offsets. |\n| `SelectionDirection` | Type | Selects backward, neutral, or forward selection direction. |\n| `TextEdit` | Type | Replaces one range with new text. |\n| `Marker` | Type | Describes an editor diagnostic marker. |\n| `MarkerSeverity` | Type | Selects an editor marker severity. |\n\n## Lower-level exports\n\nThe edit entrypoint also exposes the state-management, keyboard-resolution,\nmarker-rendering, and popover-placement building blocks used by `Editor`.\n\n| Export | Kind | Purpose |\n| --------------------------------------- | -------- | --------------------------------------------------------------------- |\n| `ManagedEditSession` | Type | Selects mutable in-progress editor state by editor type. |\n| `ManagedFileEditSession` | Type | Holds mutable state for an active file editor session. |\n| `ManagedFileDiffEditSession` | Type | Holds mutable state for an active file-diff editor session. |\n| `cloneEditorViewState` | Function | Clones editor selections and viewport state. |\n| `toManagedEditState` | Function | Returns complete edit state when a managed session has required data. |\n| `resolveEditorCommandFromKeyboardEvent` | Function | Resolves a keyboard event through custom and default editor keymaps. |\n| `resolveFindAgainShortcut` | Function | Recognizes the next or previous native find shortcut. |\n| `MarkerRenderOptions` | Type | Supplies marker rendering, measurement, and popover dependencies. |\n| `MarkerRenderer` | Class | Renders marker ranges and marker hover popovers. |\n| `markerSeverityDatasetKey` | Function | Maps a marker severity to its DOM dataset key. |\n| `POPOVER_BOUNDARY_LINES` | Value | Sets the document-edge fallback threshold for popover placement. |\n| `POPOVER_FLIP_HYSTERESIS_PX` | Value | Sets the clearance required before a flipped popover returns. |\n| `PopoverPlacementBounds` | Type | Describes vertical popover placement bounds. |\n| `PopoverViewportBounds` | Type | Describes all visible viewport edges for popover clamping. |\n| `PopoverManagerOptions` | Type | Supplies active-popover state callbacks to `PopoverManager`. |\n| `PopoverManager` | Class | Tracks viewport geometry and stable popover placement. |\n| `setPopoverPositionStyles` | Function | Writes the CSS properties used to position and clamp a popover. |\n\n## `EditorOptions` fields\n\n| Field | Purpose |\n| ------------------------ | -------------------------------------------------------- |\n| `historyMaxEntries` | Limits the undo stack. |\n| `ownsVerticalViewport` | Opts into vertical scroll retention at construction. |\n| `initialState` | Supplies partial or complete state on first attach. |\n| `keymap` | Adds shortcut groups checked before the defaults. |\n| `roundedSelection` | Controls rounded selection corners. |\n| `matchBrackets` | Controls matching-bracket highlights. |\n| `autoSurround` | Controls quote and bracket insertion around a selection. |\n| `languageCommentConfig` | Overrides comment tokens by language. |\n| `enabledSelectionAction` | Enables the selection action surface. |\n| `clipboard` | Supplies a text clipboard reader. |\n| `renderSelectionAction` | Produces the selection action element. |\n| `renderCaret` | Produces an externally owned caret element. |\n| `onAttach` | Receives the editor and attached surface. |\n| `onChange` | Receives the event, including its editor instance. |\n| `onComplete` | Observes the completed file or diff event. |\n| `onFocus` | Runs after the editor gains focus. |\n| `onBlur` | Runs after the editor loses focus. |\n\nFor a `file-diff` editor, view-only `initialState` can omit document and diff\nmetadata. Transferring an edited document and its undo/redo history requires the\nmatching `document`, `fileInfo`, and `diffSession` from one complete\n`EditState`.\n\n`onComplete` receives the exact frozen event that is also passed to the\ncomponent's `onEditComplete` or CodeView's `onItemEditComplete`. The editor\nobserver runs first and still runs when the component callback is missing. You\ncannot accept or reject from this API. It is here for symmetry, but most\nintegrations should use those component callbacks instead.\n\nUse `editStateKey` for ordinary same-runtime restoration. It retains the draft,\nundo/redo history, selections, horizontal code scroll, eligible vertical scroll,\nand FileDiff resume metadata without an application synchronization loop. It is\nbounded in-memory state and does not survive a reload.\n\nUse `getViewState()` and `setViewState()` for an isolated selection/view copy or\ndurable application persistence. An attached surface reports horizontal\n`scrollLeft`. It reports `scrollTop` only when `ownsVerticalViewport: true` was\npassed to the constructor and the surface exclusively owns an element viewport.\nVirtualization alone does not imply ownership; page, ancestor, and CodeView\nshared scrolling remain application/viewer state.\n\n`getEditState()` exposes the raw objects from the latest complete edit-lifecycle\ncheckpoint. Checkpoints run after synchronization, document edits, explicit\n`setViewState()` calls, recycling, and completion. Selection or scroll movement\nalone does not update it; use `getViewState()` for an exact live copy. State\nremains available while rendering is recycled and during `onComplete`, and\nreturns `undefined` before synchronization or after completion. The result is\nborrowed editor-owned state rather than a serialization format.\n\n## `Editor` members\n\n| Member | Purpose |\n| -------------------------------------------------------- | ------------------------------------------------------- |\n| `new Editor(type, options?, editStateKey?)` | Creates an editor with optional keyed state retention. |\n| `type` | Identifies the editor as `file` or `file-diff`. |\n| `edit(instance)` | Attaches and returns the normal completion disposer. |\n| `setOptions(options)` | Merges editor options. |\n| `applyEdits(edits, updateHistory?)` | Applies programmatic text edits. |\n| `canUndo` | Reports whether undo has an entry. |\n| `canRedo` | Reports whether redo has an entry. |\n| `undo()` | Reverts the latest edit. |\n| `redo()` | Reapplies the latest reverted edit. |\n| `getFile()` | Gets the current file contents. |\n| `getText()` | Gets the current text. |\n| `getViewState()` | Gets selections and editor-owned view state. |\n| `setViewState(state)` | Sets selections and editor-owned view state. |\n| `getEditState()` | Gets the latest edit-lifecycle state checkpoint. |\n| `setSelections(selections)` | Sets directed selection ranges. |\n| `setCarets(carets)` | Replaces the externally owned caret and highlight list. |\n| `setMarkers(markers)` | Sets diagnostic markers. |\n| `focus(options?)` | Focuses the editor. |\n| `blur()` | Removes editor focus. |\n| `cleanUp(reason?: 'discard' \\| 'recycle' \\| 'complete')` | Suspends rendering or completes the editing session. |\n\n`editStateKey` opts an editor into retained in-memory sessions across editor\ninstances. File and file-diff namespaces are independent and each keeps up to\n100 inactive entries by default. The same type/key cannot be active in two\neditors at once.\n\nCall the disposer returned by `edit(instance)` for the normal session-ending\npath; it is equivalent to `cleanUp('complete')` and installs an accepted\ncompletion result. `cleanUp('discard')` still publishes the completion event but\ndoes not install its result. `cleanUp('recycle')` suspends rendering without\nending the session or changing the editor-component association. Calling\n`edit(instance)` again resumes rendering for that same component.\n\n## `EditStateManager` members\n\n| Member | Purpose |\n| ----------------------------------- | --------------------------------------------------------------- |\n| `get(type, editStateKey)` | Borrows active or inactive complete state without touching LRU. |\n| `clear(type, editStateKey, parts?)` | Clears inactive complete or granular state. |\n| `clearAll()` | Clears all inactive state without mutating active editors. |\n| `setCapacity(capacity)` | Sets each namespace's inactive retained-state capacity. |\n\n`clear()` returns `false` for active or missing state. Omit `parts` to remove\nthe complete entry. `{ document: true }` also removes the complete entry because\nall other parts depend on it. Use `{ history: true }`, `{ selections: true }`,\n`{ view: true }`, or `{ editor: true }` to keep the document while clearing undo\nhistory, cursor state, scroll state, or both view-state parts respectively.\n\nFor durable persistence, store `FileContents` and optional JSON-safe\n`EditorViewState` separately, then construct a fresh `TextDocument` when\nrestoring. Complete `EditState` and undo/redo history are not serialization\ncontracts.\n\n## `TextDocument` members\n\n| Member | Purpose |\n| ---------------------------------------------------- | ----------------------------------------------------- |\n| `new TextDocument(uri, text, languageId?, version?)` | Creates a text document. |\n| `uri` | Gets the document identifier. |\n| `languageId` | Gets the language identifier. |\n| `version` | Gets the document version. |\n| `lineCount` | Gets the line count. |\n| `eol` | Gets the line-ending sequence. |\n| `canUndo` | Reports whether undo has an entry. |\n| `canRedo` | Reports whether redo has an entry. |\n| `positionAt(offset)` | Converts an offset to a position. |\n| `positionsAt(offsets)` | Converts several offsets to positions. |\n| `offsetAt(position)` | Converts a position to an offset. |\n| `getText(range?)` | Gets all text or one range. |\n| `getLineText(line, includeLineBreak?)` | Gets one line. |\n| `normalizeEol(text)` | Converts text to the document line ending. |\n| `getLineLength(line, includeLineBreak?)` | Gets one line length. |\n| `charAt(offsetOrPosition)` | Gets one character. |\n| `getTextSlice(start, end)` | Gets text between two offsets. |\n| `findNextNonOverlappingSubstring(needle, occupied)` | Finds an unused substring range. |\n| `search(params)` | Finds text ranges. |\n| `applyEdits(edits, ...)` | Resolves and applies position-based edits. |\n| `resolveEdits(edits)` | Converts position-based edits to offset edits. |\n| `applyResolvedEdits(edits, ...)` | Applies offset-based edits. |\n| `setLastUndoSelectionsAfter(selections)` | Associates selections with the latest history entry. |\n| `setLastUndoLineAnnotations(before, after)` | Associates annotations with the latest history entry. |\n| `undo()` | Reverts one document history entry. |\n| `redo()` | Reapplies one document history entry. |\n| `normalizePosition(position)` | Clamps a position to the document. |\n","isInternal":false,"tokens":3196,"sizeBytes":18018},{"name":"api-highlighting.md","path":"skills/diffs/references/api-highlighting.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/diffs/references/api-highlighting.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Highlighting API\n\n`preferredHighlighter` selects `'shiki-js'` (default), `'shiki-wasm'`, or\n`'highlights'`. Backends load lazily. File, FileDiff, Editor, FileStream, SSR\npreload options, and worker highlighter options accept this selection.\n\nOnly one backend type can be loaded per JavaScript realm (page, worker, or SSR\nprocess). Requests without `preferredHighlighter` use the loaded type, else\n`'shiki-js'`. Shared-highlighter requests (components, `getSharedHighlighter`,\n`preloadHighlighter`) keep using the loaded type even when they name another\none; they do not throw. `createHighlighter` with another type throws. To switch\ntypes, dispose every instance of the loaded type, shared or from\n`createHighlighter`. `getHighlighterType()` returns the loaded type.\n\n## Shared highlighter\n\n```ts\nimport { getSharedHighlighter } from '@pierre/diffs';\n\nconst highlighter = await getSharedHighlighter({\n preferredHighlighter: 'highlights',\n themes: ['pierre-dark'],\n langs: ['typescript'],\n});\nconst html = highlighter.codeToHtml('const value = 1;', {\n lang: 'typescript',\n theme: 'pierre-dark',\n});\n```\n\n`DiffsHighlighter` is an abstract class with `name`, `themeResolver`,\n`getTheme`, `codeToHtml`, `codeToTokens`, `createEditorTokenizer`,\n`createStreamTokenizer`, `loadLanguages`, `hasLoadedLanguages`,\n`attachLanguages`, and `dispose`. Highlights bundles its lexers, so its language\nmethods do nothing and `hasLoadedLanguages` is true until disposal. Import\nbackend-specific Shiki APIs and types from `shiki` directly.\n\n| Export | Purpose |\n| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |\n| `getSharedHighlighter` | Gets or creates the shared instance and loads themes/languages. |\n| `createHighlighter` | Creates an independently disposable instance: `createHighlighter('highlights')`. |\n| `getHighlighterType` | Returns the backend type loaded in this realm, if any. |\n| `preloadHighlighter` | Loads the same settings before a render. |\n| `getHighlighterIfLoaded` | Gets the loaded shared instance when its requested settings are available. |\n| `isHighlighterLoaded`, `isHighlighterLoading`, `isHighlighterNull` | Inspect shared state without arguments. Use `getHighlighterIfLoaded()` to obtain a ready instance. |\n| `disposeHighlighter` | Disposes the shared instance and clears resolved caches; retained `createHighlighter` instances keep their themes. |\n| `getHighlighterOptions` | Converts component options to highlighter input. |\n| `getHighlighterThemeStyles` | Creates component CSS from a loaded theme. |\n| `getThemes` | Converts a theme name or light/dark pair to a name list. |\n\n## Themes\n\n`DiffsTheme` contains `name`, `type`, `fg`, `bg`, optional editor `colors`, and\nbackend syntax data: `textmate` for Shiki and `zed` for Highlights. Bundled\nPierre and Shiki theme names also resolve to bundled Highlights palettes.\n\n| Export | Purpose |\n| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |\n| `registerCustomTheme(name, loader, type = 'textmate')` | Registers a loader with type `'textmate'` for Shiki, `'zed'` for Highlights, or `'diffs'` for portable themes. |\n| `createCSSVariablesTheme` | Creates a portable palette; accepts name, variablePrefix (default `--diffs-`), variableDefaults, and fontStyle. |\n| `registerCustomCSSVariableTheme` | Preserves `(name, variableDefaults, fontStyle = false)` and the `--diffs-` prefix. |\n| `resolveTheme`, `resolveThemes` | Resolve themes; optional second argument selects the backend. |\n| `getResolvedOrResolveTheme`, `getResolvedThemes`, `hasResolvedThemes` | Read or populate the selected backend's cache. |\n| `attachResolvedThemes` | Seeds resolved themes into a highlighter, including worker instances. |\n| `areThemesAttached` | Checks cached themes; optionally takes a backend name or highlighter. |\n| `cleanUpResolvedThemes` | Clears caches, preserving registrations. |\n\n`createCSSVariablesTheme` previously re-exported Shiki's\n`createCssVariablesTheme`, whose default prefix is `--shiki-` and whose result\nis a raw Shiki registration. Pass `variablePrefix: '--shiki-'` to keep\nstylesheets written for that default, or import Shiki's helper directly when a\nraw registration is needed.\n\nLoaders return a theme directly or as a module's `default` export. Register one\nloader per name and type; explicit TextMate or Zed loaders take priority over a\nshared Diffs loader. TextMate and Diffs names must match the registration. Zed\nthemes use the registered name instead of their display name; a `ThemeFamily`\nuses its first member unless the loader selects another.\n\nResolve themes on the main thread before passing them to workers. For one theme\nacross backends, use `createCSSVariablesTheme` or a `DiffsTheme` containing both\n`textmate` (Shiki's normalized `ThemeRegistrationResolved`) and `zed` palettes.\n\n## Languages\n\n`registerCustomLanguage(name, loader, extensions?)` registers TextMate grammars\nfor Shiki. Highlights includes its supported lexers and ignores custom grammar\nregistrations. Explicit unknown languages fall back to plain text in Highlights.\n\n`resolveLanguage(s)`, `getResolvedLanguages`, `hasResolvedLanguages`,\n`getResolvedOrResolveLanguage`, `attachResolvedLanguages`,\n`areLanguagesAttached`, and `cleanUpResolvedLanguages` support Shiki grammar\nloading. Language loader/cache maps remain available for compatibility.\n\n## Rendering and streams\n\n`renderFileWithHighlighter` and `renderDiffWithHighlighter` create component\nsyntax trees from backend-independent tokens.\n\nUse `highlighter.createStreamTokenizer(options)` for incremental append-only\ninput and `highlighter.createEditorTokenizer(options)` for document editing.\n`FileStream` connects a readable code stream through `setup(source, wrapper)`,\naccepts `preferredHighlighter`, supports `setThemeType`, and releases its stream\nthrough `cleanUp()`.\n","isInternal":false,"tokens":1369,"sizeBytes":7860},{"name":"api-react.md","path":"skills/diffs/references/api-react.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/diffs/references/api-react.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# React API\n\nThis reference lists the React-specific exports from `@pierre/diffs/react`. The\nentry also re-exports every type in [Shared types](api-types.md).\n\n## Components and hooks\n\n| Export | Kind | Purpose |\n| --------------------------- | --------- | --------------------------------------------------------- |\n| `File` | Component | Renders one code file. |\n| `FileDiff` | Component | Renders pre-parsed diff metadata. |\n| `MultiFileDiff` | Component | Parses and renders an old and new file pair. |\n| `PatchDiff` | Component | Parses and renders one unified patch string. |\n| `UnresolvedFile` | Component | Renders and resolves merge conflicts in one file. |\n| `CodeView` | Component | Renders a virtualized list of files and diffs. |\n| `Virtualizer` | Component | Provides simple viewport virtualization. |\n| `useVirtualizer` | Hook | Gets the nearest simple `Virtualizer` instance. |\n| `EditProvider` | Component | Supplies an editor factory. |\n| `useCreateEditor` | Hook | Gets the nearest editor factory. |\n| `WorkerPoolContextProvider` | Component | Creates and supplies a worker pool. |\n| `useWorkerPool` | Hook | Gets the nearest worker pool. |\n| `useFileInstance` | Hook | Creates and manages a vanilla `File` instance. |\n| `useFileDiffInstance` | Hook | Creates and manages a vanilla `FileDiff` instance. |\n| `useStableCallback` | Hook | Returns a stable callback that reads the latest function. |\n\n## Component and provider types\n\n| Export | Purpose |\n| ----------------------------------- | ----------------------------------------------------------------- |\n| `FileProps` | Defines props for `File`. |\n| `FileOptions` | Defines vanilla file options and the React `options` prop. |\n| `FileDiffProps` | Defines props for `FileDiff`. |\n| `MultiFileDiffProps` | Defines props for `MultiFileDiff`. |\n| `PatchDiffProps` | Defines props for `PatchDiff`. |\n| `UnresolvedFileProps` | Defines props for `UnresolvedFile`. |\n| `UnresolvedFileReactOptions` | Defines merge-conflict options for React. |\n| `DiffBasePropsReact` | Defines props shared by React diff components. |\n| `CodeViewProps` | Defines controlled or uncontrolled `CodeView` props. |\n| `ControlledCodeViewProps` | Defines `CodeView` props with `items`. |\n| `UncontrolledCodeViewProps` | Defines `CodeView` props with `initialItems`. |\n| `CodeViewReactOptions` | Defines the React-safe `CodeView` option set. |\n| `CodeViewHandle` | Defines imperative list, selection, scroll, and editor controls. |\n| `EditorFactory` | Re-exports the editor factory type from `@pierre/diffs/edit`. |\n| `EditProviderProps` | Defines the type-aware `EditProvider` factory prop. |\n| `MergeConflictActionsTypeOption` | Selects no actions, default actions, or a custom action renderer. |\n| `RenderMergeConflictActionContext` | Supplies conflict resolution to a custom action renderer. |\n| `RenderMergeConflictActions` | Defines a custom conflict action renderer. |\n| `WorkerInitializationRenderOptions` | Defines initial worker languages and render options. |\n| `WorkerPoolOptions` | Defines the worker factory, pool size, and cache size. |\n\n## Contexts and render helpers\n\n| Export | Kind | Purpose |\n| ------------------------- | -------- | ------------------------------------------------------ |\n| `EditContext` | Context | Holds the editor factory. |\n| `WorkerPoolContext` | Context | Holds the worker pool. |\n| `VirtualizerContext` | Context | Holds the simple virtualizer. |\n| `GutterUtilitySlotStyles` | Value | Supplies style keys for gutter utility slots. |\n| `MergeConflictSlotStyles` | Value | Supplies style keys for merge conflict slots. |\n| `noopRender` | Function | Returns no React output for an optional render slot. |\n| `renderDiffChildren` | Function | Builds React portals for diff slots. |\n| `renderFileChildren` | Function | Builds React portals for file slots. |\n| `templateRender` | Function | Renders React content through a managed template slot. |\n","isInternal":false,"tokens":990,"sizeBytes":5474},{"name":"api-rendering.md","path":"skills/diffs/references/api-rendering.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/diffs/references/api-rendering.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Low-level rendering API\n\nThis reference lists the renderer, manager, DOM helper, comparison, and constant\nexports from `@pierre/diffs`.\n\n## Contents\n\n- [Renderers](#renderers)\n- [Interaction manager](#interaction-manager)\n- [Size, scroll, and render managers](#size-scroll-and-render-managers)\n- [Comparison helpers](#comparison-helpers)\n- [Syntax tree and DOM helpers](#syntax-tree-and-dom-helpers)\n- [Layout and CSS helpers](#layout-and-css-helpers)\n- [Constants](#constants)\n\n## Renderers\n\n| Export | Kind | Purpose |\n| -------------------------------------- | ----- | ------------------------------------------------------- |\n| `FileRenderer` | Class | Converts one file to highlighted HAST, CSS, and HTML. |\n| `FileRendererOptions` | Type | Adds header mode to base code options. |\n| `FileRenderResult` | Type | Holds file HAST, CSS, row counts, and buffers. |\n| `DiffHunksRenderer` | Class | Converts diff hunks to highlighted column HAST and CSS. |\n| `DiffHunksRendererOptions` | Type | Configures one hunk renderer. |\n| `DiffHunksRendererOptionsWithDefaults` | Type | Describes resolved hunk renderer options. |\n| `HunksRenderResult` | Type | Holds rendered diff columns, metadata, and row count. |\n| `RenderedLineContext` | Type | Supplies line state to a line decoration. |\n| `LineDecoration` | Type | Defines a custom line wrapper and injected rows. |\n| `InjectedRow` | Type | Defines one row inserted around a unified line. |\n| `SplitInjectedRow` | Type | Defines one row inserted around a split line. |\n| `UnifiedInjectedRowPlacement` | Type | Selects placement before or after a unified row. |\n| `SplitInjectedRowPlacement` | Type | Selects side and placement for a split row. |\n| `UnifiedLineDecorationProps` | Type | Supplies one unified row to a decoration. |\n| `SplitLineDecorationProps` | Type | Supplies paired split rows to a decoration. |\n\n## Interaction manager\n\n| Export | Kind | Purpose |\n| ------------------------------- | -------- | ------------------------------------------------------------------------ |\n| `InteractionManager` | Class | Handles hover, token, gutter, and line selection events. |\n| `InteractionManagerMode` | Type | Selects file or diff interaction data. |\n| `InteractionManagerBaseOptions` | Type | Defines interaction callbacks and enabled features. |\n| `InteractionManagerOptions` | Type | Adds required DOM access to base interaction options. |\n| `GetHoveredLineResult` | Type | Describes the current hovered file or diff line. |\n| `GetLineIndexUtility` | Type | Maps a logical line to row and column indexes. |\n| `OnLineClickProps` | Type | Describes a file line click. |\n| `OnLineEnterLeaveProps` | Type | Describes file line pointer entry or exit. |\n| `OnDiffLineClickProps` | Type | Describes a diff line click. |\n| `OnDiffLineEnterLeaveProps` | Type | Describes diff line pointer entry or exit. |\n| `OnTokenEventProps` | Type | Selects file or diff token event data. |\n| `SelectionWriteOptions` | Type | Configures callback emission, the active side, and line-only highlights. |\n| `MergeConflictActionTarget` | Type | Describes a merge conflict action element. |\n| `LogTypes` | Type | Selects interaction log categories. |\n| `pluckInteractionOptions` | Function | Selects interaction fields from component options. |\n\n## Size, scroll, and render managers\n\n| Export | Kind | Purpose |\n| --------------------------------- | -------- | ------------------------------------------------------------- |\n| `ResizeManager` | Class | Measures rows, annotations, and column CSS values. |\n| `ResizeManagerColumnVariableMode` | Type | Selects column variable measurement or application. |\n| `ResizeManagerSetupOptions` | Type | Configures annotation and column measurement. |\n| `ScrollSyncManager` | Class | Synchronizes additions and deletions column scroll positions. |\n| `queueRender` | Function | Adds a callback to the shared animation render queue. |\n| `dequeueRender` | Function | Removes a callback from the shared render queue. |\n| `clearRenderQueue` | Function | Removes all callbacks from the shared render queue. |\n\n## Comparison helpers\n\n| Export | Purpose |\n| ----------------------------- | ------------------------------------------------- |\n| `areDiffLineAnnotationsEqual` | Compares two diff annotation arrays. |\n| `areLineAnnotationsEqual` | Compares two file annotation arrays. |\n| `areDiffRenderOptionsEqual` | Compares resolved diff render options. |\n| `areFileRenderOptionsEqual` | Compares resolved file render options. |\n| `areDiffTargetsEqual` | Compares two diff interaction targets. |\n| `areFilesEqual` | Compares two file inputs. |\n| `areHunkDataEqual` | Compares two hunk data objects. |\n| `areObjectsEqual` | Performs the package's shallow object comparison. |\n| `areOptionsEqual` | Compares component option objects. |\n| `arePrePropertiesEqual` | Compares calculated `pre` properties. |\n| `areRenderRangesEqual` | Compares two render ranges. |\n| `areSelectionsEqual` | Compares editor selection arrays. |\n| `areThemesEqual` | Compares theme names or light/dark pairs. |\n| `areVirtualWindowSpecsEqual` | Compares two virtual window descriptions. |\n| `areWorkerStatsEqual` | Compares two worker statistics objects. |\n\n## Syntax tree and DOM helpers\n\n| Export | Kind | Purpose |\n| -------------------------------- | -------- | ---------------------------------------------------------- |\n| `createAnnotationElement` | Function | Creates a HAST annotation row from an annotation span. |\n| `createAnnotationWrapperNode` | Function | Creates a DOM host for an annotation slot. |\n| `createDiffSpanDecoration` | Function | Creates one inline diff decoration. |\n| `pushOrJoinSpan` | Function | Adds or joins one inline diff span. |\n| `createEmptyRowBuffer` | Function | Creates an empty virtual row buffer. |\n| `createFileHeaderElement` | Function | Creates a file or diff header HAST element. |\n| `CreateFileHeaderElementProps` | Type | Defines header source, mode, and sticky state. |\n| `createGutterGap` | Function | Creates a gutter gap HAST element. |\n| `createGutterItem` | Function | Creates a gutter item HAST element. |\n| `createGutterWrapper` | Function | Creates a gutter wrapper HAST element. |\n| `createGutterUtilityElement` | Function | Creates a gutter utility HAST element. |\n| `createGutterUtilityContentNode` | Function | Creates a gutter utility DOM content host. |\n| `createHastElement` | Function | Creates a typed HAST element. |\n| `createIconElement` | Function | Creates a sprite icon HAST element. |\n| `createTextNodeElement` | Function | Creates a HAST text node. |\n| `createNoNewlineElement` | Function | Creates the missing-final-newline HAST element. |\n| `createPreElement` | Function | Creates the outer HAST `pre` element. |\n| `createPreWrapperProperties` | Function | Creates HAST properties for a `pre` wrapper. |\n| `createRowNodes` | Function | Creates DOM row and content elements for one line. |\n| `createSeparator` | Function | Creates a hunk separator HAST element. |\n| `createSpanFromToken` | Function | Creates a HAST span from one highlighted token. |\n| `createStyleElement` | Function | Creates a DOM style element with an attribute marker. |\n| `createThemeStyleElement` | Function | Creates a marked theme style element. |\n| `createUnsafeCSSStyleNode` | Function | Creates a marked custom CSS style element. |\n| `findCodeElement` | Function | Finds the code element in a HAST tree. |\n| `getLineNodes` | Function | Gets rendered line nodes from a HAST root. |\n| `getOrCreateCodeNode` | Function | Reuses or creates a code column DOM node. |\n| `getLineAnnotationName` | Function | Creates the slot name for a line annotation. |\n| `getHunkSeparatorSlotName` | Function | Creates the slot name for a hunk separator. |\n| `getIconForType` | Function | Maps a file change type to a sprite icon. |\n| `processLine` | Function | Applies line render state to one HAST line. |\n| `setPreNodeProperties` | Function | Applies resolved render properties to a DOM `pre` element. |\n| `prerenderHTMLIfNecessary` | Function | Adds preloaded HTML to an empty host element. |\n\n## Layout and CSS helpers\n\n| Export | Purpose |\n| -------------------------------- | ------------------------------------------------------------- |\n| `createWindowFromScrollPosition` | Calculates a virtual window from scroll measurements. |\n| `isDefaultRenderRange` | Tests whether a render range covers the default full range. |\n| `prefersReducedMotion` | Reads the reduced-motion media preference. |\n| `formatCSSVariablePrefix` | Creates the global or token CSS variable prefix. |\n| `wrapCoreCSS` | Places core CSS in its cascade layer. |\n| `wrapThemeCSS` | Places theme CSS in its layer and mode selector. |\n| `wrapUnsafeCSS` | Places custom CSS in its cascade layer. |\n| `patchScrollbarGutterSize` | Updates the measured scrollbar gutter in theme CSS. |\n| `detachString` | Copies a retained substring to an independent backing string. |\n| `releaseStringDetachBuffer` | Resets the reusable string copy buffer. |\n| `SVGSpriteSheet` | Contains the SVG symbols used by rendered controls. |\n| `SVGSpriteNames` | Names a symbol in `SVGSpriteSheet`. |\n\n## Constants\n\n| Export | Purpose |\n| ------------------------------------------ | ----------------------------------------------------- |\n| `DEFAULT_THEMES` | Provides the default light and dark theme names. |\n| `DEFAULT_TOKENIZE_MAX_LENGTH` | Provides the default total tokenization limit. |\n| `DEFAULT_COLLAPSED_CONTEXT_THRESHOLD` | Provides the default hidden-context threshold. |\n| `DEFAULT_EXPANDED_REGION` | Provides the default hunk expansion state. |\n| `DEFAULT_RENDER_RANGE` | Provides the full render range. |\n| `EMPTY_RENDER_RANGE` | Provides an empty render range. |\n| `DEFAULT_VIRTUAL_FILE_METRICS` | Provides estimated file header and line heights. |\n| `DEFAULT_CODE_VIEW_FILE_METRICS` | Provides list item height estimates. |\n| `DEFAULT_CODE_VIEW_LAYOUT` | Provides an empty list layout. |\n| `DEFAULT_SMOOTH_SCROLL_SETTINGS` | Provides the default smooth scroll settings. |\n| `DIFFS_TAG_NAME` | Provides the `diffs-container` custom element name. |\n| `CORE_CSS_ATTRIBUTE` | Provides the core style marker attribute. |\n| `THEME_CSS_ATTRIBUTE` | Provides the theme style marker attribute. |\n| `UNSAFE_CSS_ATTRIBUTE` | Provides the custom style marker attribute. |\n| `DIFFS_SCROLLBAR_MEASURE_ATTRIBUTE` | Provides the scrollbar measurement attribute. |\n| `DIFFS_SCROLLBAR_GUTTER_MEASURED_PROPERTY` | Provides the measured scrollbar CSS property. |\n| `CODE_VIEW_HEADER_ATTRIBUTE` | Provides the list header host attribute. |\n| `CODE_VIEW_FOOTER_ATTRIBUTE` | Provides the list footer host attribute. |\n| `CUSTOM_HEADER_SLOT_ID` | Provides the custom header slot ID. |\n| `HEADER_PREFIX_SLOT_ID` | Provides the header prefix slot ID. |\n| `HEADER_FILENAME_SUFFIX_SLOT_ID` | Provides the filename suffix slot ID. |\n| `HEADER_METADATA_SLOT_ID` | Provides the header metadata slot ID. |\n| `HUNK_HEADER` | Provides the patch hunk header marker. |\n| `FILE_CONTEXT_BLOB` | Matches a patch hunk boundary. |\n| `INDEX_LINE_METADATA` | Provides the patch index metadata marker. |\n| `COMMIT_METADATA_SPLIT` | Provides the commit metadata separator expression. |\n| `FILENAME_HEADER_REGEX` | Matches a standard patch file header. |\n| `GIT_DIFF_FILE_BREAK_REGEX` | Matches a Git patch file boundary. |\n| `UNIFIED_DIFF_FILE_BREAK_REGEX` | Matches a unified patch file boundary. |\n| `MERGE_CONFLICT_START_MARKER_REGEX` | Matches a conflict start marker. |\n| `MERGE_CONFLICT_BASE_MARKER_REGEX` | Matches a conflict base marker. |\n| `MERGE_CONFLICT_SEPARATOR_MARKER_REGEX` | Matches a conflict separator marker. |\n| `MERGE_CONFLICT_END_MARKER_REGEX` | Matches a conflict end marker. |\n| `SPLIT_WITH_NEWLINES` | Splits text while it preserves newline tokens. |\n| `DIFFS_DEVELOPMENT_BUILD` | Reports whether the package uses a development build. |\n","isInternal":false,"tokens":2997,"sizeBytes":16105},{"name":"api-ssr.md","path":"skills/diffs/references/api-ssr.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/diffs/references/api-ssr.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# SSR API\n\nThis reference lists the SSR-specific exports from `@pierre/diffs/ssr`. The\nentry also re-exports every type in [Shared types](api-types.md).\n\n## Functions\n\n| Export | Purpose |\n| --------------------------- | ------------------------------------------------------------- |\n| `preloadFile` | Renders one file and returns props with `prerenderedHTML`. |\n| `preloadFileDiff` | Renders pre-parsed diff metadata and returns component props. |\n| `preloadMultiFileDiff` | Parses and renders an old and new file pair. |\n| `preloadPatchDiff` | Parses and renders one patch for `PatchDiff`. |\n| `preloadPatchFile` | Parses a multi-file patch and returns one result per file. |\n| `preloadUnresolvedFile` | Renders one merge-conflict file and returns component props. |\n| `preloadDiffHTML` | Renders a diff directly to an HTML string. |\n| `preloadUnresolvedFileHTML` | Renders a merge-conflict file directly to an HTML string. |\n| `renderHTML` | Serializes rendered HAST elements to HTML. |\n\n## Types\n\n| Export | Purpose |\n| ------------------------------ | -------------------------------------------------------- |\n| `PreloadFileOptions` | Defines input for `preloadFile`. |\n| `PreloadedFileResult` | Adds `prerenderedHTML` to file input. |\n| `PreloadDiffOptions` | Defines parsed or file-pair input for `preloadDiffHTML`. |\n| `PreloadFileDiffOptions` | Defines input for `preloadFileDiff`. |\n| `PreloadFileDiffResult` | Adds `prerenderedHTML` to parsed diff input. |\n| `PreloadMultiFileDiffOptions` | Defines input for `preloadMultiFileDiff`. |\n| `PreloadMultiFileDiffResult` | Adds `prerenderedHTML` to file-pair input. |\n| `PreloadPatchDiffOptions` | Defines input for `preloadPatchDiff`. |\n| `PreloadPatchDiffResult` | Adds `prerenderedHTML` to patch input. |\n| `PreloadPatchFileOptions` | Defines input for `preloadPatchFile`. |\n| `PreloadUnresolvedFileOptions` | Defines input for `preloadUnresolvedFile`. |\n| `PreloadUnresolvedFileResult` | Adds `prerenderedHTML` to merge-conflict input. |\n","isInternal":false,"tokens":531,"sizeBytes":2551},{"name":"api-types.md","path":"skills/diffs/references/api-types.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/diffs/references/api-types.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Shared types\n\nThis reference lists every export from the shared `@pierre/diffs` type module.\nThe root, React, and SSR entries re-export these types.\n\n## Contents\n\n- [Files and patches](#files-and-patches)\n- [Themes and options](#themes-and-options)\n- [Annotations and selection](#annotations-and-selection)\n- [`CodeView` types](#codeview-types)\n- [Lines, hunks, and render state](#lines-hunks-and-render-state)\n- [Render results and virtualization](#render-results-and-virtualization)\n- [Tokenization and diff types](#tokenization-and-diff-types)\n\n## Files and patches\n\n| Export | Purpose |\n| ------------------------------- | ----------------------------------------------------------------- |\n| `FileContents` | Describes a file name, text, language, header, and cache key. |\n| `DiffFileInput` | Accepts an old and new file for changes, additions, or deletions. |\n| `MaybeDiffFileInput` | Accepts a file pair or no file input. |\n| `FileDiffContentsLoader` | Loads complete files for partial diff metadata. |\n| `FileDiffLoadedChangedFiles` | Returns both files for a loaded changed diff. |\n| `FileDiffLoadedPureRenamedFile` | Returns the new file for a loaded pure rename. |\n| `FileDiffLoadedFiles` | Represents either loaded-file result. |\n| `ChangeTypes` | Names changed, renamed, added, or deleted file states. |\n| `ParsedPatch` | Holds patch metadata and parsed files. |\n| `ContextContent` | Describes one unchanged hunk block. |\n| `ChangeContent` | Describes one additions and deletions block. |\n| `Hunk` | Describes one parsed patch hunk. |\n| `FileDiffMetadata` | Holds parsed file names, lines, hunks, and change metadata. |\n| `MergeConflictMarkerRowType` | Names a merge conflict marker row. |\n| `MergeConflictMarkerRow` | Describes one marker row and its source line. |\n| `MergeConflictRegion` | Describes one parsed merge conflict region. |\n| `MergeConflictResolution` | Selects current, incoming, or both conflict contents. |\n| `MergeConflictActionPayload` | Describes one conflict action and region. |\n| `ProcessFileConflictData` | Holds state while patch parsing processes conflicts. |\n| `ConflictResolverTypes` | Names current, incoming, or both conflict choices. |\n\n## Themes and options\n\n| Export | Purpose |\n| ------------------------------------ | -------------------------------------------------------------- |\n| `SupportedLanguages` | Accepts a bundled, text, ANSI, or custom language name. |\n| `HighlighterTypes` | Selects shiki-js, shiki-wasm, or highlights. |\n| `HighlightedToken` | Stores a character index, foreground, and token text. |\n| `DiffsThemeNames` | Accepts a bundled or custom theme name. |\n| `ThemesType` | Maps light and dark schemes to theme names. |\n| `ThemeTypes` | Selects system, light, or dark mode. |\n| `DiffsHighlighter` | Defines backend-independent tokenization and theme resolution. |\n| `BaseCodeOptions` | Configures themes, wrapping, headers, tokenization, and CSS. |\n| `BaseDiffOptions` | Adds layout, indicators, context, and line diff options. |\n| `BaseDiffOptionsWithDefaults` | Describes required diff options after defaults apply. |\n| `DiffIndicators` | Selects classic, bar, or hidden diff indicators. |\n| `HunkSeparators` | Selects the hunk separator presentation. |\n| `LineDiffTypes` | Selects word, alternate word, character, or no inline diff. |\n| `FileHeaderRenderMode` | Selects a default or custom file header. |\n| `CustomPreProperties` | Defines custom properties for the rendered `pre` element. |\n| `PrePropertiesConfig` | Describes calculated `pre` element properties. |\n| `ExtensionFormatMap` | Maps file names or extensions to languages. |\n| `RenderHeaderPrefixCallback` | Produces prefix content for a diff header. |\n| `RenderHeaderFilenameSuffixCallback` | Produces filename suffix content for a diff header. |\n| `RenderHeaderMetadataCallback` | Produces metadata content for a diff header. |\n| `RenderFileMetadata` | Produces header content for a file. |\n| `PostRenderPhase` | Names mount, update, or unmount callback phases. |\n\n## Annotations and selection\n\n| Export | Purpose |\n| -------------------- | ----------------------------------------------------- |\n| `AnnotationSide` | Selects deletions or additions for an annotation. |\n| `LineAnnotation` | Associates metadata with one file line. |\n| `DiffLineAnnotation` | Associates metadata with one side and line. |\n| `AnnotationLineMap` | Groups diff annotations by line number. |\n| `SelectedLineRange` | Describes a selected start and end across diff sides. |\n| `SelectionSide` | Selects deletions or additions for a selection. |\n| `SelectionPoint` | Describes one line and optional side. |\n\n## `CodeView` types\n\n| Export | Purpose |\n| --------------------------------- | -------------------------------------------------------- |\n| `CodeViewFileItem` | Describes one file item in a virtualized list. |\n| `CodeViewDiffItem` | Describes one diff item in a virtualized list. |\n| `CodeViewItem` | Represents a file or diff list item. |\n| `CodeViewCreateEditorOptions` | Provides CodeView's routed editor option subset. |\n| `CodeViewItemEditCompleteHandler` | Handles completion with correlated event and item types. |\n| `CodeViewScrollBehavior` | Selects instant, smooth, or automatic smooth scroll. |\n| `CodeViewScrollTarget` | Represents any supported list scroll target. |\n| `CodeViewPositionScrollTarget` | Scrolls to an absolute list position. |\n| `CodeViewLineScrollTarget` | Scrolls to one item line. |\n| `CodeViewRangeScrollTarget` | Scrolls to one item line range. |\n| `CodeViewItemScrollTarget` | Scrolls to one item boundary. |\n| `NumericScrollLineAnchor` | Describes a numeric position inside a line. |\n| `CodeViewLayout` | Stores item offsets, heights, and total list height. |\n| `PendingCodeViewLayoutReset` | Describes a deferred list layout reset. |\n| `SmoothScrollSettings` | Configures duration and distance for smooth list scroll. |\n\n`CodeViewCreateEditorOptions` currently contains the routed `onChange(event)`\ncallback that `CodeView` uses to emit `onItemEditChange(event, item)`; it does\nnot add an item ID. A `CodeViewOptions.createEditor` factory also receives the\noptional `editStateKey` returned by `getEditStateKey(item)` as its third\nargument. Forward that key separately to the editor constructor. It retains the\neditable draft, undo/redo history, selections, and horizontal code scroll. Item\neditors never own CodeView's shared vertical position.\n\n`onItemEditComplete(event, item, nextItem)` must return `'accept'` to accept the\ncompleted item or `'reject'` to restore the original while the item remains\npresent; a missing callback rejects. During removal or teardown, neither\ndecision reinserts the item. Controlled owners must put the supplied `nextItem`\ninto their item state when accepting an item that should remain. If the item\nuses keyed render caching, assigning a fresh `cacheKey` to the accepted event\nfile or diff invalidates that cache.\n\n## Lines, hunks, and render state\n\n| Export | Purpose |\n| ---------------------------- | --------------------------------------------------------------- |\n| `HunkLineType` | Names context, expanded, addition, deletion, or metadata lines. |\n| `HunkData` | Describes one hunk's render indexes and line ranges. |\n| `HunkExpansionRegion` | Describes expanded context above and below a hunk. |\n| `ExpansionDirections` | Selects up, down, or both expansion directions. |\n| `DiffAcceptRejectHunkType` | Selects accept, reject, or both hunk controls. |\n| `DiffAcceptRejectHunkConfig` | Configures hunk accept and reject behavior. |\n| `GapSpan` | Describes an empty row span. |\n| `AnnotationSpan` | Describes an annotation row span. |\n| `LineSpans` | Represents a gap or annotation span. |\n| `LineTypes` | Names rendered context and change line classes. |\n| `LineInfo` | Describes a rendered line number, side, and type. |\n| `CodeColumnType` | Selects unified, additions, or deletions columns. |\n| `LineEventBaseProps` | Supplies a file line to an interaction callback. |\n| `DiffLineEventBaseProps` | Supplies a diff line and side to an interaction callback. |\n| `TokenEventBase` | Supplies a token and source event. |\n| `DiffTokenEventBaseProps` | Adds diff side data to a token event. |\n| `ObservedAnnotationNodes` | Stores DOM nodes for observed annotations. |\n| `ObservedGridNodes` | Stores DOM nodes for observed grid columns. |\n| `SharedRenderState` | Holds shared token transformer render state. |\n| `StickySpecs` | Describes sticky header position and height. |\n\n## Render results and virtualization\n\n| Export | Purpose |\n| --------------------------- | ------------------------------------------------------- |\n| `RenderFileOptions` | Defines the resolved options for a highlighted file. |\n| `RenderDiffOptions` | Defines the resolved options for a highlighted diff. |\n| `ForceFilePlainTextOptions` | Selects a plain-text file range. |\n| `ForceDiffPlainTextOptions` | Selects a plain-text diff range and hunk state. |\n| `ThemedFileResult` | Holds the highlighted file syntax tree and line count. |\n| `ThemedDiffResult` | Holds highlighted additions and deletions syntax trees. |\n| `RenderDiffFilesResult` | Holds the resolved old and new file inputs. |\n| `RenderFileResult` | Holds file output and the options that produced it. |\n| `RenderDiffResult` | Holds diff output and the options that produced it. |\n| `RenderedFileASTCache` | Stores one cached file syntax tree by theme. |\n| `RenderedDiffASTCache` | Stores one cached diff syntax tree by theme. |\n| `AppliedThemeStyleCache` | Stores applied light and dark theme CSS. |\n| `RenderRange` | Describes a start row, row count, and buffer sizes. |\n| `RenderWindow` | Describes first and last rows in a render window. |\n| `VirtualWindowSpecs` | Describes viewport position, height, and row window. |\n| `VirtualFileMetrics` | Describes estimated header and line heights. |\n\n## Tokenization and diff types\n\n| Export | Purpose |\n| ----------------------------------------------------- | -------------------------------------------------------------------- |\n| `DiffsTheme` | Shared editor colors with optional TextMate and Zed syntax palettes. |\n| `ThemedToken` | One styled token with content, offset, color, and optional styles. |\n| `TokensResult` | Token rows and root colors/styles. |\n| `CodeToTokensOptions`, `CodeToHtmlOptions` | Select a language, themes, and tokenization limits. |\n| `DiffsStreamTokenizer` | Incremental tokenization of appended chunks. |\n| `DiffsEditorTokenizer`, `DiffsEditorTokenizerOptions` | Incremental tokenization of document edits. |\n| `CreatePatchOptionsNonabortable` | Configures the underlying patch algorithm. |\n\nImport TextMate registration and Shiki transformer types from `shiki`. Diffs no\nlonger re-exports Shiki's public API.\n","isInternal":false,"tokens":2676,"sizeBytes":14073},{"name":"api-worker.md","path":"skills/diffs/references/api-worker.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/diffs/references/api-worker.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Worker API\n\nThis reference lists every export from `@pierre/diffs/worker`, every public\n`WorkerPoolManager` member, and both worker script entries.\n\n## Runtime exports\n\n| Export | Kind | Purpose |\n| -------------------------------- | -------- | ----------------------------------------------------- |\n| `WorkerPoolManager` | Class | Runs file and diff highlighting across a worker pool. |\n| `getOrCreateWorkerPoolSingleton` | Function | Gets or creates the module-wide worker pool. |\n| `terminateWorkerPoolSingleton` | Function | Terminates and clears the module-wide worker pool. |\n\n## `WorkerPoolManager` members\n\n| Member | Purpose |\n| -------------------------------------------------------------- | ------------------------------------------------- |\n| `new WorkerPoolManager(options, renderOptions)` | Creates a worker pool. |\n| `initialize(languages?)` | Starts workers and loads languages. |\n| `isInitialized()` | Reports whether initialization finished. |\n| `isWorkingPool()` | Reports whether workers can accept work. |\n| `setRenderOptions(options)` | Updates theme and render settings in each worker. |\n| `getFileRenderOptions()` | Gets active file render options. |\n| `getDiffRenderOptions()` | Gets active diff render options. |\n| `highlightFileAST(instance, file)` | Queues a highlighted file result for an instance. |\n| `highlightDiffAST(instance, diff)` | Queues a highlighted diff result for an instance. |\n| `primeFileHighlightCache(file)` | Preloads one highlighted file result. |\n| `primeDiffHighlightCache(diff)` | Preloads one highlighted diff result. |\n| `getFileResultCache(file)` | Gets one cached file result. |\n| `getDiffResultCache(diff)` | Gets one cached diff result. |\n| `getPlainFileAST(file, start, total, lines?)` | Gets a plain-text file result. |\n| `getPlainDiffAST(diff, start, total, expansions?, threshold?)` | Gets a plain-text diff result. |\n| `inspectCaches()` | Gets both result caches. |\n| `evictFileFromCache(cacheKey)` | Removes one file cache entry. |\n| `evictDiffFromCache(cacheKey)` | Removes one diff cache entry. |\n| `subscribeToThemeChanges(instance)` | Subscribes a render instance to theme changes. |\n| `unsubscribeToThemeChanges(instance)` | Removes a theme subscription. |\n| `subscribeToStatChanges(callback)` | Subscribes to worker statistics. |\n| `cleanUpTasks(instance)` | Removes queued and active tasks for an instance. |\n| `getStats()` | Gets worker and cache statistics. |\n| `terminate()` | Stops workers and clears pool resources. |\n\n## Configuration and state types\n\n| Export | Purpose |\n| ----------------------------------- | ----------------------------------------------------------------- |\n| `SetupWorkerPoolProps` | Combines pool and highlighter options for the singleton. |\n| `WorkerPoolOptions` | Defines the worker factory, pool size, and cache size. |\n| `WorkerInitializationRenderOptions` | Defines initial languages, theme, highlighter, and diff settings. |\n| `WorkerRenderingOptions` | Defines the complete worker render settings. |\n| `WorkerStats` | Describes pool state, work counts, subscribers, and cache sizes. |\n| `WorkerRequestId` | Identifies one worker request. |\n| `ResolvedLanguage` | Holds a resolved language registration. |\n| `FileRendererInstance` | Defines callbacks for a file render consumer. |\n| `DiffRendererInstance` | Defines callbacks for a diff render consumer. |\n\n## Request and response types\n\n| Export | Purpose |\n| ------------------------------- | ------------------------------------------------------- |\n| `WorkerRequest` | Represents any request sent to a worker. |\n| `InitializeWorkerRequest` | Starts a worker with themes, languages, and options. |\n| `SetRenderOptionsWorkerRequest` | Updates render options and themes. |\n| `RenderFileRequest` | Requests one file render. |\n| `RenderDiffRequest` | Requests one diff render. |\n| `SubmitRequest` | Represents a file or diff request before ID assignment. |\n| `WorkerResponse` | Represents any worker response. |\n| `InitializeSuccessResponse` | Confirms worker initialization. |\n| `RegisterThemeSuccessResponse` | Confirms a render-option and theme update. |\n| `RenderSuccessResponse` | Represents a successful file or diff render. |\n| `RenderFileSuccessResponse` | Returns one file render result. |\n| `RenderDiffSuccessResponse` | Returns one diff render result. |\n| `RenderErrorResponse` | Returns a serialized worker error. |\n\n## Task types\n\n| Export | Purpose |\n| ---------------------------- | ------------------------------------------------- |\n| `AllWorkerTasks` | Represents any manager task. |\n| `InitializeWorkerTask` | Tracks one initialization request. |\n| `SetRenderOptionsWorkerTask` | Tracks one render-option update. |\n| `RenderFileTask` | Tracks one file render request and its consumers. |\n| `RenderDiffTask` | Tracks one diff render request and its consumers. |\n| `RenderTaskCallbacks` | Resolves or rejects one render task consumer. |\n\n## Worker script entries\n\n| Import | Purpose |\n| ----------------------------------------- | -------------------------------------------------------------------------------- |\n| `@pierre/diffs/worker/worker.js` | Supplies the module worker that uses package dependencies. |\n| `@pierre/diffs/worker/worker-portable.js` | Supplies a single script with all highlighter backends and dependencies bundled. |\n\nFor static hosting, copy `dist/worker/worker-portable.js` and start it with\n`new Worker(url)`. It also supports module workers and blob URLs, including VS\nCode webviews, without another bundling step. All backends are included in the\ndownload; only the selected backend is initialized. For lazy backend loading,\nuse the regular worker entry with your bundler.\n\nThe pool resolves themes and Shiki grammars on the main thread and sends them to\nthe worker. Their catalogs are excluded from the portable script.\n\nA pool is optional. When one is supplied, highlighting goes through its workers\nfor every backend. Highlights is often fast enough on the main thread to skip\nthe pool.\n","isInternal":false,"tokens":1370,"sizeBytes":8400},{"name":"recipe-annotations.md","path":"skills/diffs/references/recipe-annotations.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/diffs/references/recipe-annotations.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Recipe: add line annotations and selection\n\nPass annotation data and a renderer to the surface:\n\n```tsx\nimport type { DiffLineAnnotation } from '@pierre/diffs/react';\nimport { MultiFileDiff } from '@pierre/diffs/react';\n\nconst annotations: DiffLineAnnotation<{ message: string }>[] = [\n {\n side: 'additions',\n lineNumber: 8,\n metadata: { message: 'Review this line.' },\n },\n];\n\n

{annotation.metadata.message}

}\n options={{\n enableLineSelection: true,\n onLineSelectionEnd(range) {\n saveSelection(range);\n },\n }}\n/>;\n```\n\nUse `LineAnnotation` for a single file. Use `DiffLineAnnotation` for a diff.\nControl the active selection with the `selectedLines` prop.\n","isInternal":false,"tokens":199,"sizeBytes":814},{"name":"recipe-code-view.md","path":"skills/diffs/references/recipe-code-view.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/diffs/references/recipe-code-view.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Recipe: build a `CodeView`\n\nUse `CodeView` when one scroll region contains many files, diffs, or both. It\nmanages item virtualization, sticky headers, list-wide selection, and item or\nline scroll targets.\n\n## Contents\n\n- [Select item ownership](#select-item-ownership)\n- [Define items](#define-items)\n- [Use controlled React state](#use-controlled-react-state)\n- [Use imperative ownership](#use-imperative-ownership)\n- [Enable item edit mode](#enable-item-edit-mode)\n\n## Select item ownership\n\n| Host and data flow | Input | Update API |\n| ------------------------------------------- | ----------------- | ------------------------------------ |\n| React owns the complete list | `items` | Publish a new `items` array. |\n| React hosts a large or append-only list | `initialItems` | Use the `CodeViewHandle` methods. |\n| Vanilla JavaScript owns the viewer instance | `setItems(items)` | Use the `CodeView` instance methods. |\n\nKeep one ownership mode for the life of a mounted React viewer. Use controlled\nstate when item data already belongs to React. Use imperative ownership for a\nlarge or streamed list.\n\n## Define items\n\nGive each item a stable and unique `id`. Use a `file` item for `FileContents`.\nUse a `diff` item for `FileDiffMetadata`.\n\nIncrement `version` when an existing item changes its contents, annotations,\ncollapsed state, or edit state. `CodeView` uses the ID and version to select the\nitem that it must update.\n\n## Use controlled React state\n\n```tsx\nimport {\n parseDiffFromFile,\n type CodeViewItem,\n type CodeViewLineSelection,\n} from '@pierre/diffs';\nimport { CodeView, type CodeViewHandle } from '@pierre/diffs/react';\nimport { useRef, useState } from 'react';\n\nconst oldFile = {\n name: 'src/value.ts',\n contents: 'export const value = 1;',\n};\nconst newFile = {\n name: 'src/value.ts',\n contents: 'export const value = 2;',\n};\nconst codeViewStyle = { height: 600, overflow: 'auto' } as const;\nconst codeViewOptions = {\n theme: { light: 'pierre-light', dark: 'pierre-dark' },\n stickyHeaders: true,\n enableLineSelection: true,\n layout: { paddingTop: 16, paddingBottom: 16, gap: 12 },\n} as const;\n\nexport function ReviewSurface() {\n const viewerRef = useRef | null>(null);\n const [selection, setSelection] = useState(\n null\n );\n const [items, setItems] = useState(() => [\n {\n id: 'diff:src/value.ts',\n type: 'diff',\n fileDiff: parseDiffFromFile(oldFile, newFile),\n version: 0,\n },\n {\n id: 'file:README.md',\n type: 'file',\n file: { name: 'README.md', contents: '# Review notes' },\n version: 0,\n },\n ]);\n\n function toggleDiff() {\n setItems((current) =>\n current.map((item) =>\n item.id === 'diff:src/value.ts'\n ? {\n ...item,\n collapsed: !item.collapsed,\n version: (item.version ?? 0) + 1,\n }\n : item\n )\n );\n }\n\n return (\n <>\n \n \n viewerRef.current?.scrollTo({\n type: 'line',\n id: 'diff:src/value.ts',\n lineNumber: 1,\n side: 'additions',\n align: 'center',\n })\n }\n >\n Jump to change\n \n \n \n );\n}\n```\n\n## Use imperative ownership\n\nIn React, pass `initialItems` and keep `items` unset. Use the component ref to\ncall `addItems`, `getItem`, `updateItem`, `updateItemId`, or `scrollTo`.\n\nIn vanilla JavaScript, configure and populate the instance directly:\n\n```ts\nimport { CodeView, parseDiffFromFile } from '@pierre/diffs';\n\nconst root = document.querySelector('#review');\nif (root == null) throw new Error('Missing review host');\n\nconst oldFile = {\n name: 'src/value.ts',\n contents: 'export const value = 1;',\n};\nconst newFile = {\n name: 'src/value.ts',\n contents: 'export const value = 2;',\n};\n\nconst viewer = new CodeView({\n theme: { light: 'pierre-light', dark: 'pierre-dark' },\n stickyHeaders: true,\n enableLineSelection: true,\n onSelectedLinesChange(selection) {\n console.log('selected lines', selection);\n },\n});\n\nroot.style.height = '600px';\nroot.style.overflow = 'auto';\nviewer.setup(root);\nviewer.setItems([\n {\n id: 'diff:src/value.ts',\n type: 'diff',\n fileDiff: parseDiffFromFile(oldFile, newFile),\n version: 0,\n },\n]);\n\nviewer.addItems([\n {\n id: 'file:README.md',\n type: 'file',\n file: { name: 'README.md', contents: '# Review notes' },\n version: 0,\n },\n]);\nviewer.scrollTo({\n type: 'item',\n id: 'diff:src/value.ts',\n align: 'start',\n});\n\nconst item = viewer.getItem('diff:src/value.ts');\nif (item != null) {\n viewer.updateItem({\n ...item,\n collapsed: true,\n version: (item.version ?? 0) + 1,\n });\n}\n\nexport function removeReviewSurface() {\n viewer.cleanUp();\n}\n```\n\n## Enable item edit mode\n\nIn React, wrap `CodeView` in `EditProvider`. In vanilla JavaScript, pass\n`createEditor(editorType, options, editStateKey)` in `CodeViewOptions` and\nforward all three arguments to `new Editor`. Set `edit: true` on each editable\nitem and increment its version. The factory receives `'file'` or `'file-diff'`\nas its first argument so it can construct an editor of the requested type.\n\n`onItemEditChange(event, item)` reports live contents and annotation changes.\nRead the current document from `event.file`, the complete annotation collection\nfrom `event.lineAnnotations`. Treat it as a notification and do not feed the\nchanges back into the viewer.\n\n`onItemEditComplete(event, item, nextItem)` must return `'accept'` or `'reject'`\nwhenever a session ends, including when its final text is unchanged. `CodeView`\nbuilds `nextItem` with the completed contents and annotations, `edit: false`,\nand an incremented `version`. If you use keyed render caching, assign a fresh\n`cacheKey` to `event.file` or `event.fileDiff` before accepting. Return\n`'accept'` to install `nextItem` while the item remains present, or `'reject'`\nto restore the original item while it remains present. During removal or viewer\nteardown, neither decision reinserts the item. A missing callback rejects. When\nReact controls `items`, put `nextItem` into controlled state only when the item\nshould remain.\n\nUse `getEditStateKey(item)` to opt into retaining the draft, undo/redo history,\nselections, and editor-owned view state across editor instances. The returned\n`editStateKey` is passed to the editor factory. `getEditor(id)` returns the\ncurrent `Editor` instance.\n\nRead [Edit with React](recipe-edit-react.md) or\n[Edit with vanilla JavaScript](recipe-edit-vanilla.md) for the complete editor\nlifecycle.\n","isInternal":false,"tokens":1727,"sizeBytes":7076},{"name":"recipe-custom-highlighting.md","path":"skills/diffs/references/recipe-custom-highlighting.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/diffs/references/recipe-custom-highlighting.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Recipe: register custom highlighting\n\nRegister themes before rendering. For a Zed-compatible theme with Highlights:\n\n```tsx\nimport { registerCustomTheme } from '@pierre/diffs';\nimport { FileDiff } from '@pierre/diffs/react';\n\nregisterCustomTheme('app-dark', () => import('./my-zed-theme.json'), 'zed');\n\n;\n```\n\nFor TextMate themes and custom grammars, use Shiki:\n\n```ts\nimport { registerCustomLanguage, registerCustomTheme } from '@pierre/diffs';\n\nregisterCustomLanguage(\n 'my-language',\n () => import('./my-language.tmLanguage.json'),\n ['myext']\n);\nregisterCustomTheme('my-theme', () => import('./my-textmate-theme.json'));\n```\n\nSet `file.lang` and `options.theme` to the registered names. Custom languages\napply to Shiki; Highlights bundles its lexers and ignores custom grammars.\n\nFor a CSS palette that works across backends:\n\n```ts\nimport { registerCustomCSSVariableTheme } from '@pierre/diffs';\n\nregisterCustomCSSVariableTheme('app-palette', {\n foreground: '#eeeeee',\n background: '#101010',\n 'token-keyword': '#c084fc',\n 'token-string-expression': '#86efac',\n});\n```\n\nThis registers a shared Diffs theme using `--diffs-*` variables. See\n[Highlighting API](api-highlighting.md#themes) for loader formats, name\nmatching, and CSS palette options.\n","isInternal":false,"tokens":342,"sizeBytes":1382},{"name":"recipe-edit-react.md","path":"skills/diffs/references/recipe-edit-react.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/diffs/references/recipe-edit-react.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Recipe: edit with React\n\nMount one `EditProvider` above the editable surfaces. Its factory receives the\neditor type, the surface's creation-time `editorOptions`, and an optional\n`editStateKey`. Each active surface or `CodeView` item owns its editor.\n\nPass `editStateKey` to opt into bounded in-memory retention of the draft,\nundo/redo history, selections, horizontal scroll, eligible vertical scroll, and\ndiff resume metadata across editor instances. Choose this key explicitly; it is\na stable application identity for the document. The same active key cannot be\nshared by two editors of the same type.\n\n## Contents\n\n- [Edit a standalone file or diff](#edit-a-standalone-file-or-diff)\n- [Keep annotations synchronized](#keep-annotations-synchronized)\n- [Edit CodeView items](#edit-codeview-items)\n\n## Edit a standalone file or diff\n\nSet `edit` on `File`, `FileDiff`, `MultiFileDiff`, or `PatchDiff`. Pass editor\ncreation options through `editorOptions` and optional retention through\n`editStateKey`.\n\n```tsx\nimport type { FileContents, FileDiffOptions } from '@pierre/diffs';\nimport {\n Editor,\n type EditorChangeEvent,\n type EditorFactory,\n type EditorOptions,\n type FileDiffEditCompleteEvent,\n} from '@pierre/diffs/edit';\nimport { EditProvider, MultiFileDiff, Virtualizer } from '@pierre/diffs/react';\nimport { useMemo, useRef, useState } from 'react';\n\nconst oldFile: FileContents = {\n name: 'src/value.ts',\n contents: 'export const value = 1;',\n};\nconst initialNewFile: FileContents = {\n name: 'src/value.ts',\n contents: 'export const value = 2;',\n};\nconst diffOptions: FileDiffOptions = {\n theme: { light: 'pierre-light', dark: 'pierre-dark' },\n diffStyle: 'split',\n};\n\nconst createEditor: EditorFactory = (\n editorType,\n options,\n editStateKey?: string\n) => new Editor(editorType, options, editStateKey);\n\nexport function EditableDiff() {\n const [edit, setEdit] = useState(false);\n const [newFile, setNewFile] = useState(initialNewFile);\n const editorRef = useRef | null>(null);\n const editorOptions = useMemo<\n EditorOptions<'file-diff', undefined, undefined>\n >(\n () => ({\n onAttach(editor) {\n editorRef.current = editor;\n },\n }),\n []\n );\n\n function toggleEdit() {\n setEdit((value) => !value);\n }\n\n function handleEditChange(\n event: EditorChangeEvent<'file-diff', undefined, undefined>\n ) {\n saveDraft(event.file);\n }\n\n function handleEditComplete(\n event: FileDiffEditCompleteEvent\n ) {\n if (event.newFile != null) {\n setNewFile(event.newFile);\n }\n return 'accept' as const;\n }\n\n return (\n \n \n editorRef.current?.undo()}\n >\n Undo\n \n \n \n \n \n );\n}\n```\n\nMount the provider near the application root when many surfaces use edit mode.\nAlways forward all three factory arguments. Use `onAttach` when controls need\n`undo`, `redo`, `applyEdits`, selections, markers, focus, or other editor APIs.\n`EditStateManager` only manages sessions retained with `editStateKey`; unkeyed\nsessions require no manager cleanup. For keyed sessions, use\n`EditStateManager.clear(type, key)` after a session becomes inactive when its\nretained draft should be discarded. `clearAll()` clears inactive state in both\nnamespaces, and `setCapacity(capacity)` changes each namespace's default limit\nof 100 entries. Active state is never mutated by manager clearing.\n\n## Keep annotations synchronized\n\nEdit mode owns annotation positions during an active session. Change events\nexpose the remapped collection for observation, but do not feed it back into the\nsurface. On acceptance, store the completion event's final annotations beside\nthe accepted file or diff. Use `isFileAnnotationCollection` or\n`isDiffAnnotationCollection` when the surface type is not already known, and key\nannotation UI state by a stable metadata ID instead of a line number.\n\n## Edit `CodeView` items\n\nWrap `CodeView` in the same `EditProvider`. Set `edit: true` on an item and\nincrement its `version`. Pass shared creation options through the `CodeView`\n`editorOptions` prop. Use `getEditStateKey(item)` for opt-in draft, history,\nselection, and view-state retention.\n\nUse `onItemEditChange` for live contents and annotation changes. Use\n`onItemEditComplete` to accept or reject every ended session, including when its\nfinal text is unchanged. If you use keyed render caching, assign a fresh\n`cacheKey` to the event's file or diff. Put the supplied `nextItem` into\ncontrolled state only while the item should remain, then return `'accept'`;\nacceptance during removal or teardown does not reinsert it. `CodeView` builds\n`nextItem` with `edit: false` and an incremented `version`.\n\n`CodeViewHandle.getEditor(id)` returns the current `Editor` instance. The item\neditor keeps its active document and history when virtualization or collapse\nremoves the item from the rendered window. `getEditStateKey` extends that\nretention to later editor instances after the edit session ends.\n\nWhen a worker pool highlights an editable surface, set\n`useTokenTransformer: true` in the worker `highlighterOptions`.\n","isInternal":false,"tokens":1356,"sizeBytes":5790},{"name":"recipe-edit-vanilla.md","path":"skills/diffs/references/recipe-edit-vanilla.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/diffs/references/recipe-edit-vanilla.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Recipe: edit with vanilla JavaScript\n\nRender a standalone surface first. Then attach one `Editor` to it. Use one\neditor for each surface that can be edited at the same time.\n\n## Contents\n\n- [Edit a standalone diff](#edit-a-standalone-diff)\n- [Edit CodeView items](#edit-codeview-items)\n\n## Edit a standalone diff\n\n```ts\nimport {\n FileDiff,\n type DiffLineAnnotation,\n type FileContents,\n} from '@pierre/diffs';\nimport { Editor } from '@pierre/diffs/edit';\n\ninterface ThreadMetadata {\n id: string;\n}\n\nconst hostElement = document.querySelector('#diff');\nif (hostElement == null) throw new Error('Missing diff host');\nconst host: HTMLElement = hostElement;\n\nconst oldFile: FileContents = {\n name: 'src/value.ts',\n contents: 'export const value = 1;',\n};\nlet newFile: FileContents = {\n name: 'src/value.ts',\n contents: 'export const value = 2;',\n};\nlet annotations: DiffLineAnnotation[] = [\n {\n side: 'additions',\n lineNumber: 1,\n metadata: { id: 'value-review' },\n },\n];\nconst view = new FileDiff({\n theme: { light: 'pierre-light', dark: 'pierre-dark' },\n onEditChange(event) {\n saveDraft(event.file);\n },\n onEditComplete(event) {\n if (event.newFile != null) {\n newFile = event.newFile;\n }\n if (event.lineAnnotations != null) {\n annotations = event.lineAnnotations;\n }\n return 'accept';\n },\n renderAnnotation(annotation) {\n const element = document.createElement('p');\n element.textContent = 'Thread ' + annotation.metadata.id;\n return element;\n },\n});\n\nfunction render() {\n view.render({\n fileContainer: host,\n oldFile,\n newFile,\n lineAnnotations: annotations,\n });\n}\n\nrender();\n\nconst editor = new Editor<'file-diff', ThreadMetadata>(\n 'file-diff',\n {},\n 'src/value.ts:draft'\n);\nlet finishEditing: (() => void) | undefined = editor.edit(view);\n\nexport function stopEditing() {\n const finish = finishEditing;\n finishEditing = undefined;\n finish?.();\n}\n\nexport function removeSurface() {\n stopEditing();\n view.cleanUp();\n}\n```\n\n`onEditChange` receives one `EditorChangeEvent`. Observe its remapped\n`lineAnnotations`, but do not feed them back into the surface during the active\nsession. Store the final collection from `onEditComplete` alongside the accepted\nfile or diff. Use stable metadata IDs for application state that belongs to an\nannotation.\n\nPass a third `editStateKey` argument to `new Editor` when a later editor\ninstance should resume/save the in-memory draft, undo/redo history, selections,\nand editor-owned view state.\n\nUse `VirtualizedFile` or `VirtualizedFileDiff` with a `Virtualizer` for a large\nstandalone surface. Load `@pierre/diffs/edit` with `import()` when edit mode is\noptional and the initial bundle must omit the editor.\n\n## Edit `CodeView` items\n\nPass a factory through `CodeViewOptions.createEditor`:\n\n```ts\nimport { CodeView } from '@pierre/diffs';\nimport { Editor } from '@pierre/diffs/edit';\n\nexport function mountEditableCodeView(root: HTMLElement) {\n const viewer = new CodeView({\n getEditStateKey(item) {\n return 'draft:' + item.id;\n },\n createEditor(editorType, options, editStateKey) {\n return new Editor(editorType, options, editStateKey);\n },\n onItemEditChange(event, item) {\n saveItemDraft(item.id, event.file, event.lineAnnotations);\n },\n onItemEditComplete(event, item, nextItem) {\n if (item.type !== 'file' || !('file' in event)) return 'reject';\n\n // Re-key only if this item participates in keyed render caching.\n event.file.cacheKey = item.id + ':v' + nextItem.version;\n return 'accept';\n },\n });\n\n viewer.setup(root);\n viewer.setItems([\n {\n id: 'file:src/value.ts',\n type: 'file',\n file: {\n name: 'src/value.ts',\n contents: 'export const value = 1;',\n },\n edit: true,\n version: 0,\n },\n ]);\n\n return viewer;\n}\n```\n\nSet `edit: true` on an item and increment its `version`. `onItemEditChange`\nreceives `(event, item)`; use `event.file` and `event.lineAnnotations` without\nfeeding the change back into the viewer. Completion receives\n`(event, item, nextItem)` whenever a session ends, including when its final text\nis unchanged. `CodeView` builds `nextItem` with the final contents and\nannotations, `edit: false`, and an incremented `version`. If you use keyed\nrender caching, assign a fresh `cacheKey` to `event.file` or `event.fileDiff`.\nReturn `'accept'` to install `nextItem` while the item remains present or\n`'reject'` to restore the original item while it remains present. During removal\nor viewer teardown, neither decision reinserts the item. A missing completion\ncallback rejects. A controlled React owner should put `nextItem` into its\n`items` state only when the item should remain.\n\n`getEditStateKey(item)` opts an item into draft, undo/redo, selection, and\neditor-owned view-state retention across editor instances. Forward the resulting\nthird factory argument to `new Editor`. `CodeView` creates and removes the item\neditors.\n\n`viewer.getEditor(id)` returns the current `Editor` instance. Call\n`viewer.cleanUp()` when the host removes the viewer.\n\nWhen a worker pool highlights an editable surface, set\n`useTokenTransformer: true` in the worker `highlighterOptions`.\n","isInternal":false,"tokens":1278,"sizeBytes":5269},{"name":"recipe-react.md","path":"skills/diffs/references/recipe-react.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/diffs/references/recipe-react.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Recipe: render with React\n\n## Select a surface\n\n| Input or layout | Component |\n| ------------------------------------------- | ---------------- |\n| One `FileContents` object | `File` |\n| Old and new `FileContents` objects | `MultiFileDiff` |\n| Existing `FileDiffMetadata` | `FileDiff` |\n| One unified patch string | `PatchDiff` |\n| One file with merge conflicts | `UnresolvedFile` |\n| One scroll region with many files and diffs | `CodeView` |\n\nUse `MultiFileDiff` when the app has old and new file contents:\n\n```tsx\nimport { MultiFileDiff } from '@pierre/diffs/react';\n\n;\n```\n\nPass source data, annotations, and slot renderers as component props. Pass\ndisplay, theme, interaction, and highlighting settings through `options`.\n\nKeep file objects and option objects stable when their values do not change.\nWrap a large standalone surface in `Virtualizer`. Use `CodeView` when one scroll\nregion contains a list of files or diffs.\n\nUse the matching preload function from `@pierre/diffs/ssr` when the server must\nrender the initial highlighted markup.\n","isInternal":false,"tokens":308,"sizeBytes":1391},{"name":"recipe-ssr.md","path":"skills/diffs/references/recipe-ssr.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/diffs/references/recipe-ssr.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Recipe: preload a diff on the server\n\nCreate props on the server and pass the result to the matching React component:\n\n```tsx\nimport { preloadMultiFileDiff } from '@pierre/diffs/ssr';\nimport { MultiFileDiff } from '@pierre/diffs/react';\n\nconst preloaded = await preloadMultiFileDiff({\n oldFile: { name: 'src/value.ts', contents: oldSource },\n newFile: { name: 'src/value.ts', contents: newSource },\n options: { theme: 'pierre-dark', diffStyle: 'split' },\n});\n\n;\n```\n\nSelect the preload function that matches the client component. Use\n`preloadDiffHTML` or `preloadUnresolvedFileHTML` when the host needs an HTML\nstring only.\n","isInternal":false,"tokens":167,"sizeBytes":661},{"name":"recipe-vanilla.md","path":"skills/diffs/references/recipe-vanilla.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/diffs/references/recipe-vanilla.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Recipe: render with vanilla JavaScript\n\n## Select a surface\n\n| Input or layout | Class |\n| ------------------------------------------- | --------------------- |\n| One `FileContents` object | `File` |\n| Existing or parsed `FileDiffMetadata` | `FileDiff` |\n| One file with merge conflicts | `UnresolvedFile` |\n| One large file | `VirtualizedFile` |\n| One large diff | `VirtualizedFileDiff` |\n| One scroll region with many files and diffs | `CodeView` |\n\nParse the files, create the view, and render it into a host:\n\n```ts\nimport { FileDiff, parseDiffFromFile } from '@pierre/diffs';\n\nconst host = document.querySelector('#diff');\nif (host == null) throw new Error('Missing diff host');\n\nconst fileDiff = parseDiffFromFile(\n { name: 'src/value.ts', contents: oldSource },\n { name: 'src/value.ts', contents: newSource }\n);\n\nconst view = new FileDiff({\n diffStyle: 'split',\n theme: 'pierre-dark',\n});\n\nview.render({ fileContainer: host, fileDiff });\n```\n\nKeep the class instance while the host remains mounted. Call `render` again when\nthe source data changes. Call `setOptions`, `setThemeType`,\n`setLineAnnotations`, or `setSelectedLines` for targeted updates.\n\nUse a `Virtualizer` with `VirtualizedFile` or `VirtualizedFileDiff` for one\nlarge surface. Use `CodeView` for a list that shares one scroll region. Call\n`cleanUp()` when the host removes the surface.\n","isInternal":false,"tokens":348,"sizeBytes":1563},{"name":"recipe-workers.md","path":"skills/diffs/references/recipe-workers.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/diffs/references/recipe-workers.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Recipe: use a worker pool\n\nWrap React diff surfaces in one provider:\n\n```tsx\nimport { WorkerPoolContextProvider } from '@pierre/diffs/react';\n\n\n new Worker(new URL('@pierre/diffs/worker/worker.js', import.meta.url), {\n type: 'module',\n }),\n }}\n highlighterOptions={{\n langs: ['typescript', 'tsx'],\n theme: { light: 'pierre-light', dark: 'pierre-dark' },\n }}\n>\n {children}\n;\n```\n\nFor vanilla JavaScript, call `getOrCreateWorkerPoolSingleton` and pass the\nresult as the second constructor argument to a render class. Call\n`terminateWorkerPoolSingleton()` when the application tears down the shared\npool.\n","isInternal":false,"tokens":181,"sizeBytes":744},{"name":"SKILL.md","path":"skills/diffs/SKILL.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/diffs/SKILL.md","title":"diffs","category":"anthropic-skill","format":"markdown","content":"---\nname: diffs\ndescription:\n Use when an app uses @pierre/diffs to render or edit code files, diffs,\n patches, merge conflicts, or CodeView review surfaces, including React,\n vanilla JavaScript, SSR, workers, annotations, selection, and custom syntax\n languages or themes.\n---\n\n# `@pierre/diffs`\n\nUse `@pierre/diffs` to render syntax-highlighted files and diffs. Use its\noptional editor, SSR, and worker entries for those capabilities.\n\nFor standalone HTML or token generation with `@pierre/highlights`, read the\n[highlights skill](../highlights/SKILL.md).\n\n## Install\n\n```bash\npnpm add @pierre/diffs\n```\n\nInstall `react` and `react-dom` when the app uses the React entry.\n\n## Select an API reference\n\n| Surface | Reference |\n| ------------------------------------------------------------ | ------------------------------------------------------ |\n| Root components, parsing, and file extension APIs | [Core API](references/api-core.md) |\n| Languages, themes, highlighter state, and streams | [Highlighting API](references/api-highlighting.md) |\n| Renderers, managers, DOM helpers, comparisons, and constants | [Low-level rendering API](references/api-rendering.md) |\n| Shared data, option, render, selection, and editor types | [Shared types](references/api-types.md) |\n| `@pierre/diffs/react` | [React API](references/api-react.md) |\n| `@pierre/diffs/edit` | [Editor API](references/api-editor.md) |\n| `@pierre/diffs/ssr` | [SSR API](references/api-ssr.md) |\n| `@pierre/diffs/worker` and worker scripts | [Worker API](references/api-worker.md) |\n\n## Select a recipe\n\n| Task | Recipe |\n| ----------------------------------- | ------------------------------------------------------------------------ |\n| Render a file or diff in React | [Render with React](references/recipe-react.md) |\n| Render a file or diff without React | [Render with vanilla JavaScript](references/recipe-vanilla.md) |\n| Build a virtualized review surface | [Use CodeView](references/recipe-code-view.md) |\n| Edit a React surface or CodeView | [Edit with React](references/recipe-edit-react.md) |\n| Edit a vanilla surface or CodeView | [Edit with vanilla JavaScript](references/recipe-edit-vanilla.md) |\n| Preload markup on the server | [Use SSR](references/recipe-ssr.md) |\n| Highlight through a worker pool | [Use workers](references/recipe-workers.md) |\n| Add line annotations and selection | [Add annotations and selection](references/recipe-annotations.md) |\n| Register a custom language or theme | [Register custom highlighting](references/recipe-custom-highlighting.md) |\n","frontmatter":{"name":"diffs","description":"Use when an app uses @pierre/diffs to render or edit code files, diffs, patches, merge conflicts, or CodeView review surfaces, including React, vanilla JavaScript, SSR, workers, annotations, selection, and custom syntax languages or themes."},"isInternal":false,"tokens":614,"sizeBytes":3213},{"name":"live.md","path":"skills/highlights/references/live.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/highlights/references/live.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Incremental editing\n\n`LiveTokenizer` owns a document and an isolated WebAssembly instance. It\nre-tokenizes changed lines and following lines until the lexer state converges\nwith the retained state. Constructor options extend the\n[tokenization options](rendering.md#options-and-languages) with `code` (default\nempty), `renderRange`, and `onDeferTokenize`.\n\n## Apply edits\n\n```ts\nimport { LiveTokenizer } from '@pierre/highlights';\nimport { pierreDark } from '@pierre/highlights/themes';\n\nconst live = new LiveTokenizer({\n code: 'const answer = 41;\\nconsole.log(answer);',\n lang: 'ts',\n theme: pierreDark,\n});\n\ntry {\n const update = live.applyEdits([\n {\n range: {\n start: { line: 0, character: 15 },\n end: { line: 0, character: 17 },\n },\n newText: '42',\n },\n ]);\n\n console.log(live.getLineText(0)); // const answer = 42;\n for (const change of update.lineChanges) {\n for (let line = change.newStartLine; line < change.newEndLine; line++) {\n console.log(line, live.getLineTokens(line));\n }\n }\n} finally {\n live.dispose();\n}\n```\n\nEvery edit range uses zero-based lines and UTF-16 character positions in the\ndocument before the batch. The end position is exclusive. Overlapping ranges are\nrejected before mutation. `reset(code, options?)` replaces the whole text while\nretaining language and theme options; recreate the tokenizer to change those\noptions.\n\nWithout `renderRange`, updates finish synchronously and `update.lines` is empty.\nUse `lineChanges` and `getLineTokens()` to refresh a renderer. Each\n`LiveLineChange` maps `[oldStartLine, oldEndLine)` to\n`[newStartLine, newEndLine)`; also remove deleted rows when reconciling a view.\n`LiveTokenizerUpdate` includes `revision`, `previousLineCount`, and `lineCount`.\n\n`getLineTokens(line)` returns `{ tokens, bracketIgnoredRanges }`. Its token\noffsets are relative to that line. `bracketIgnoredRanges` contains end-exclusive\nUTF-16 column pairs for strings, comments, and regexes that bracket matching\nshould skip.\n\n## Prioritize a viewport\n\n`renderRange: [startLine, endLine]` uses post-edit line numbers and excludes\n`endLine`. Pass it on each update that should prioritize a viewport. Dirty lines\nbefore the viewport must also be processed to establish lexer state; the\nremaining work runs in background slices.\n\n```ts\nimport { LiveTokenizer } from '@pierre/highlights';\nimport { pierreDark } from '@pierre/highlights/themes';\n\nconst live = new LiveTokenizer({\n code: 'const answer = 41;\\nconsole.log(answer);',\n lang: 'ts',\n theme: pierreDark,\n renderRange: [0, 1],\n onDeferTokenize(lines) {\n // This callback can run before the constructor returns.\n for (const [line, tokens] of lines) console.log(line, tokens);\n },\n});\n\ntry {\n console.log(live.getLineTokens(0)); // Read the initial viewport after construction.\n const update = live.applyEdits(\n [\n {\n range: {\n start: { line: 0, character: 15 },\n end: { line: 0, character: 17 },\n },\n newText: '42',\n },\n ],\n { renderRange: [0, 1] }\n );\n for (const [line, tokens] of update.lines) console.log(line, tokens);\n\n live.flush(); // Finish pending work before reading the complete document's tokens.\n} finally {\n live.dispose();\n}\n```\n\n`update.lines` contains re-tokenized lines inside the range, not the entire\nviewport. Finished lines outside it arrive through `onDeferTokenize`, which can\nrun synchronously during construction or an update. Keep the callback\nindependent of the variable receiving the new instance. Schedule further edits\nafter the current update; calling `applyEdits()` or `reset()` inside its\nsynchronous callback throws.\n\nBoth maps contain `HighlightedToken[]`: tuples of\n`[character, foregroundColor, text]` using the first resolved theme. Read\n`getLineTokens()` when font styles or multi-theme `htmlStyle` maps are needed.\nWhile `pendingTokenization` is true, unreached lines can retain old tokens and\nnew lines can have foreground-only tokens. Call `flush()` before reads that\nrequire fully current tokens.\n\n## Document and lifecycle API\n\n| Member | Purpose |\n| ---------------------------------------------- | ---------------------------------------------------------------------------- |\n| `revision`, `lineCount`, `pendingTokenization` | Read document revision, line count, and pending work |\n| `applyEdits(edits, options?)` | Apply a batch and return `LiveTokenizerUpdate` |\n| `reset(code, options?)` | Replace text and return `LiveTokenizerUpdate` |\n| `getLineLength(line)`, `getLineText(line)` | Read UTF-16 length or text excluding the terminator |\n| `getText()` | Read all text, preserving LF, CRLF, and lone CR |\n| `getLineTokens(line)` | Read themed tokens and bracket-ignored ranges |\n| `getLineRecords(line)` | Read packed raw token records |\n| `flush(endLine?)` | Finish pending work before an exclusive line bound, or all work when omitted |\n| `pause()`, `resume()` | Suspend or resume background tokenization |\n| `dispose()` | Release the instance and cancel deferred work; safe to repeat |\n\n`flush()`, `reset()`, and `applyEdits()` (even a no-op batch) resume paused\nwork. After disposal, other methods and state getters throw. Keep one tokenizer\nfor the document's lifetime and dispose it when the editor unmounts or closes.\n\n## Packed records\n\n`getLineRecords()` returns `LiveTokenRecords` with `revision`, `format`, and\n`data: Uint32Array`. Starts are implicit: zero for the first token, then the\nprevious token's end. End positions are UTF-16 columns within the line.\n\n| Format | Encoding |\n| ---------- | -------------------------------------------------------------------- |\n| `packed24` | One word per token: `tokenId = word >>> 24`, `end = word & 0xffffff` |\n| `wide32` | Pairs of `[endUtf16, tokenId]` for lines exceeding the 24-bit range |\n\nImport `tokenNames` from `@pierre/highlights` to map IDs to syntax scope names.\nViews are invalidated by successful edits, resets, deferred tokenization slices,\nand disposal. Copy `records.data.slice()` before retaining data across those\noperations. Deferred work can invalidate data without changing the document\nrevision.\n\nThe root entry exports `HighlightedToken`, `LiveLineChange`, `LivePosition`,\n`LiveTextEdit`, `LiveTokenizerOptions`, `LiveTokenizerUpdate`,\n`LiveTokenRecords`, and `LiveUpdateOptions`. Use `LivePosition` and\n`LiveTextEdit` for the public position and edit types.\n","isInternal":false,"tokens":1534,"sizeBytes":7072},{"name":"rendering.md","path":"skills/highlights/references/rendering.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/highlights/references/rendering.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Rendering\n\n## HTML\n\n```ts\nimport { codeToHtml } from '@pierre/highlights';\nimport { pierreDark } from '@pierre/highlights/themes';\n\nconst html = new TextDecoder().decode(\n codeToHtml('const answer = 42;', { lang: 'ts', theme: pierreDark })\n);\n```\n\n`codeToHtml()` returns UTF-8 bytes for a\n`
…
` fragment. Source text is\nHTML-escaped and theme styles are applied inline. Decode the bytes immediately,\nor call `.slice()` before retaining them across another highlighting or\ntokenization call on the same highlighter. The top-level `codeToHtml()` and\n`codeToTokens()` share one instance.\n\n## Tokens\n\n```ts\nimport { codeToTokens } from '@pierre/highlights';\nimport { pierreDark } from '@pierre/highlights/themes';\n\nconst result = codeToTokens('const answer = 42;\\n', {\n lang: 'ts',\n theme: pierreDark,\n});\n\nconsole.log(result.tokens[0]); // ThemedToken[] for the first line\nconsole.log(result.fg, result.bg); // Root foreground and background colors\n```\n\n`TokensResult.tokens` contains one `ThemedToken[]` per line. Line terminators\nare excluded from content; a trailing line break adds an empty final line.\nOffsets count UTF-16 code units from the start of the complete input.\n\n| Token field | Meaning |\n| ---------------------- | ----------------------------------------------------------------------------- |\n| `content`, `offset` | Text and its absolute UTF-16 start index |\n| `color`, `fontStyle` | Single-theme color and Shiki-style font flags |\n| `htmlStyle` | Multi-theme styles, including custom properties; apply the whole map |\n| `type` | `1` comment, `2` string, `3` regex, otherwise `0` or omitted |\n| `bgColor`, `htmlAttrs` | Optional background and span attributes for renderer/transformer integrations |\n\nHighlights emits italic (`1`) and bold (`2`) font flags. The type also supports\nunderline (`4`) and strikethrough (`8`) supplied by transformers. Use text nodes\nor escape `content` in a custom HTML renderer. Apply root colors as well as\ntoken styles. Token objects are Shiki-compatible; lexer boundaries and syntax\nclassifications can differ.\n\nWith multiple themes, `fg` and `bg` can contain CSS declaration lists, and\n`defaultColor: false` supplies `rootStyle`. See [Themes](themes.md) for\nrendering those styles. Equal runs can share an `htmlStyle` object; replace that\nobject when customizing one token.\n\n## Options and languages\n\nBoth functions accept `string`, `Uint8Array`, or `ArrayBuffer` input; bytes are\nUTF-8. Supply `lang` and exactly one of `theme` or `themes`.\n\n| Option | Meaning |\n| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- |\n| `lang` | Built-in language name or alias, typed as `Lang` |\n| `theme` | One Zed `Theme` or `ThemeFamily` object |\n| `themes` | Non-empty map of named theme objects; see [Themes](themes.md) |\n| `cssVariablePrefix` | Prefix for CSS-variable colors and theme properties; default `--hls-` |\n| `defaultColor` | With `themes`, inline theme key (default `light`), `false`, or `'light-dark()'` |\n| `tokenizeMaxLineLength` | Tokenization only: lines at or above this UTF-16 length become one token without syntax styling; `0` or omission disables it |\n\nThe line-length limit reduces token objects, while the lexer still processes the\nline to preserve subsequent state. It also applies to streaming and live\ntokenization, but is not an HTML option.\n\nLanguage names and aliases are case-insensitive. Unknown names throw\n`RangeError`. Highlights performs no automatic language detection or filename\nresolution. Validate external labels and choose an explicit fallback:\n\n```ts\nimport { isSupportedLanguage } from '@pierre/highlights';\n\nconst requestedLanguage: string = 'typescript';\nconst lang = isSupportedLanguage(requestedLanguage)\n ? requestedLanguage\n : 'plain';\n```\n\n`isSupportedLanguage()` narrows a string to `Lang`. Plain text aliases include\n`plain`, `text`, `plaintext`, and `txt`. Lexers are built in; custom TextMate\ngrammar registration belongs to the Shiki APIs in `@pierre/diffs`.\n\n## Runtime and types\n\n`createHighlighter()` returns an isolated `Highlighter` using the initialized\nmodule. Embedders can pass their own compiled `WebAssembly.Module` to\n`createHighlighter(module)` or replace the shared highlighter with\n`init(module)`. Both functions are synchronous. `Highlighter` exposes\n`codeToHtml()` and `codeToTokens()` with the signatures above. Import the normal\npackage entry for automatic initialization.\n\nCore public types are `Highlighter`, `Lang`, `CodeToHtmlBaseOptions`,\n`CodeToHtmlOptions`, `CodeToTokensBaseOptions`, `CodeToTokensOptions`,\n`ThemeOptions`, `ThemedToken`, and `TokensResult`. Theme types are covered in\n[Themes](themes.md); live types and `tokenNames` in\n[Incremental editing](live.md).\n","isInternal":false,"tokens":1152,"sizeBytes":5570},{"name":"streaming.md","path":"skills/highlights/references/streaming.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/highlights/references/streaming.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Streaming\n\n`StreamTokenizer` extends `TransformStream`. It takes\nthe [tokenization options](rendering.md#options-and-languages) and owns an\nisolated WebAssembly instance. Use it for append-only input; use\n[LiveTokenizer](live.md) when previously received text can change.\n\n## Pipe a readable stream\n\nPass a UTF-8 byte stream through the tokenizer with `pipeThrough()`. It decodes\nbytes internally, including characters split across chunks. Given an existing\n`ReadableStream` named `responseBody`:\n\n```ts\nimport { StreamTokenizer } from '@pierre/highlights';\nimport { pierreDark } from '@pierre/highlights/themes';\n\nconst lines = responseBody.pipeThrough(\n new StreamTokenizer({ lang: 'ts', theme: pierreDark })\n);\n\nfor await (const tokens of lines) {\n console.log(tokens); // One ThemedToken[] per line\n}\n```\n\nClosing the writable side emits the remaining lines and releases the instance.\nCancellation or abort discards buffered input and releases it. Let the stream\npipeline manage completion; use the synchronous methods below when manually\nfeeding strings or UTF-8 bytes.\n\n## Push chunks synchronously\n\n```ts\nimport { StreamTokenizer } from '@pierre/highlights';\nimport { pierreDark } from '@pierre/highlights/themes';\n\nconst stream = new StreamTokenizer({ lang: 'ts', theme: pierreDark });\n\ntry {\n console.log(stream.pushCode('const answer =')); // []: incomplete line\n const bytes = new TextEncoder().encode(' 42;\\nconsole.log(answer);');\n console.log(stream.pushCode(bytes)); // First line\n console.log(stream.end()); // Remaining line; also disposes the instance\n} finally {\n stream.dispose();\n}\n```\n\n| Method | Behavior |\n| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |\n| `pushCode(chunk: string \\| Uint8Array)` | Accepts text or UTF-8 bytes; returns `ThemedToken[][]` for completed lines and buffers the unfinished line |\n| `end()` | Finishes decoding and returns remaining lines, including an empty final line after a trailing terminator, then disposes |\n| `dispose()` | Discards buffered input and releases the instance; safe to repeat |\n\nChunks can produce zero or more lines. Lines are emitted when `\\n` arrives,\nincluding in CRLF input, or at `end()`. Lexer state is retained across chunks.\nToken offsets are UTF-16 indices from the start of the complete stream. Apply\nthe same token styles described in [Rendering](rendering.md#tokens).\n\nCall `end()` once when input finishes. Calling `pushCode()` or `end()` after\ndisposal throws. Keep `dispose()` in cleanup paths for cancellation and errors.\n\nUTF-8 characters can span consecutive byte chunks. Mixing strings and bytes\npreserves chunk order: a nonempty string flushes incomplete UTF-8 as a\nreplacement character before appending the string. Empty chunks leave buffered\ninput intact.\n","isInternal":false,"tokens":635,"sizeBytes":3188},{"name":"themes.md","path":"skills/highlights/references/themes.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/highlights/references/themes.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Themes\n\nHighlights takes Zed-compatible theme objects. Load them from\n`@pierre/highlights/themes`; `@pierre/theme` supplies Shiki and VS Code objects\nwith a different shape.\n\n## Load a theme\n\n```ts\nimport { pierreDark } from '@pierre/highlights/themes';\nimport vitesseDark from '@pierre/highlights/themes/vitesse-dark';\nimport { themes } from '@pierre/highlights/themes/loader';\n\nconst { default: lazyTheme } = await themes['pierre-dark']();\n```\n\n| Entry | Exports |\n| ---------------------------------- | -------------------------------------------------------- |\n| `@pierre/highlights/themes` | Camel-case named themes, `cssVariables`, and `toCSS()` |\n| `@pierre/highlights/themes/` | One theme as the default export, e.g. `pierre-dark` |\n| `@pierre/highlights/themes/loader` | `themes`, a map from bundled IDs to async module loaders |\n\nPass the resolved object as `theme`; a string ID is not accepted. A\n`ThemeFamily` resolves to its first member. Pass `family.themes[index]` to\nselect another. Theme preparation is cached by object identity; create new\nobjects when changing values.\n\nFor `@pierre/diffs` components, load these objects through\n`registerCustomTheme(name, loader, 'zed')` and select\n`preferredHighlighter: 'highlights'`. See the\n[custom highlighting recipe](../../diffs/references/recipe-custom-highlighting.md)\nfor registration and backend selection.\n\n## Custom themes\n\n```ts\nimport type { Theme } from '@pierre/highlights';\n\nconst theme = {\n name: 'App Dark',\n appearance: 'dark',\n style: {\n 'editor.background': '#101010',\n 'editor.foreground': '#eeeeee',\n syntax: {\n keyword: { color: '#c084fc', font_weight: 700 },\n comment: { color: '#888888', font_style: 'italic' },\n },\n },\n} satisfies Theme;\n```\n\nColors support three-, four-, six-, and eight-digit hex and numeric\n`color(display-p3 ...)` values. Use the CSS-variable mode below for application\nvariables. Syntax scopes such as `keyword.control` inherit from their nearest\nconfigured parent.\n\nTheme types come from `@pierre/highlights`:\n\n| Type | Shape |\n| --------------------- | -------------------------------------------------------------------- |\n| `Theme` | `name`, `appearance`, `style`, and optional `cssVariables: true` |\n| `ThemeFamily` | `themes: readonly Theme[]`, optional `name` and `author` |\n| `ThemeStyle` | Editor colors and `syntax`, plus additional Zed style keys |\n| `ThemeSyntaxSettings` | Optional `color`, `font_style`, and `font_weight` |\n| `ThemePlayer` | Optional collaborator `cursor`, `selection`, and `background` colors |\n| `ThemeOptions` | Exactly one of `theme` or `themes` |\n\nEach `style.syntax` value can be a color string or `ThemeSyntaxSettings`.\n\n## Switch colors with CSS variables\n\n```ts\nimport { codeToHtml } from '@pierre/highlights';\nimport { cssVariables, pierreDark, toCSS } from '@pierre/highlights/themes';\n\nconst cssVariablePrefix = '--code-';\nconst html = new TextDecoder().decode(\n codeToHtml('const answer = 42;', {\n lang: 'ts',\n theme: cssVariables,\n cssVariablePrefix,\n })\n);\nconst stylesheet = `.highlights { ${toCSS(pierreDark, { cssVariablePrefix })} }`;\n```\n\nInclude the stylesheet with the markup. `toCSS(theme, options?)` accepts a\n`Theme` and returns declarations without a selector. Apply them to the code\nblock or an ancestor. Keep its prefix and the highlighting prefix equal; both\ndefault to `--hls-`. Changing declarations updates colors without tokenization.\nThis mode controls colors only and ignores theme font style and weight.\n\n## Multiple themes\n\nAll highlighting and tokenization APIs accept a `themes` map. `defaultColor`\nselects how it renders:\n\n| Value | Result |\n| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- |\n| A theme key | Applies that scheme inline and emits other schemes as custom properties; defaults to `light` and throws if the key is absent |\n| `false` | Emits all schemes as custom properties for CSS to select |\n| `'light-dark()'` | Requires `light` and `dark`; merges colors into CSS `light-dark()` values following the page's `color-scheme` |\n\n```ts\nimport { codeToHtml } from '@pierre/highlights';\nimport { pierreDark, pierreLight } from '@pierre/highlights/themes';\n\nconst html = new TextDecoder().decode(\n codeToHtml('const answer = 42;', {\n lang: 'ts',\n themes: { light: pierreLight, dark: pierreDark },\n defaultColor: false,\n })\n);\n```\n\nInclude CSS to select the emitted properties:\n\n```css\n.highlights {\n color: var(--hls-light);\n background-color: var(--hls-light-bg);\n}\n\n.highlights span {\n color: var(--hls-light);\n font-style: var(--hls-light-font-style, normal);\n font-weight: var(--hls-light-font-weight, normal);\n}\n\n@media (prefers-color-scheme: dark) {\n .highlights {\n color: var(--hls-dark);\n background-color: var(--hls-dark-bg);\n }\n\n .highlights span {\n color: var(--hls-dark);\n font-style: var(--hls-dark-font-style, normal);\n font-weight: var(--hls-dark-font-weight, normal);\n }\n}\n```\n\nFor a custom token renderer, apply each token's complete `htmlStyle` map to its\nspan. With `defaultColor: false`, apply `result.rootStyle` as the container's\ninline style, then use equivalent CSS for that container. With an inline\ndefault, the root style is `background-color:${result.bg};color:${result.fg}`;\nthese fields can include additional declarations. Preserve those declarations\ninstead of treating them as single CSS color values.\n\n## Named CSS palettes\n\nA theme can use `cssVariables: { prefix, defaults }` to map syntax categories to\napplication palette variables while retaining font settings:\n\n```ts\nconst theme = {\n name: 'App palette',\n appearance: 'dark',\n cssVariables: {\n prefix: '--app-',\n defaults: { keyword: '#c084fc' },\n },\n style: {\n syntax: {\n keyword: { color: 'keyword', font_weight: 700 },\n comment: { color: 'muted', font_style: 'italic' },\n },\n },\n} satisfies Theme;\n```\n\nSyntax `color` values are variable suffixes in this mode. Unconfigured syntax\ncategories inherit the `foreground` variable, and defaults become CSS `var()`\nfallbacks. The palette prefix belongs to the theme and is independent of the\nprefix used for multiple theme output. Diffs uses this mode for its portable\n`createCSSVariablesTheme` palette.\n","isInternal":false,"tokens":1532,"sizeBytes":6853},{"name":"SKILL.md","path":"skills/highlights/SKILL.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/highlights/SKILL.md","title":"highlights","category":"anthropic-skill","format":"markdown","content":"---\nname: highlights\ndescription:\n Use when an app uses @pierre/highlights to generate syntax-highlighted HTML or\n tokens, stream code, incrementally tokenize edits, or apply Zed-compatible\n themes and CSS variables.\n---\n\n# `@pierre/highlights`\n\nUse `@pierre/highlights` for standalone syntax highlighting with built-in\nWebAssembly lexers. Choose HTML for a complete code block, tokens for a custom\nrenderer, `StreamTokenizer` for append-only input, or `LiveTokenizer` for an\neditable document.\n\n## Install\n\n```bash\npnpm add @pierre/highlights\n```\n\nImport from `@pierre/highlights`. Conditional exports initialize WebAssembly\nautomatically for Node.js, browsers, and Cloudflare Workers. Highlighting is\nsynchronous after import; ordinary usage needs no `init()` or language\nregistration.\n\n## Select a reference\n\n| Task | Reference |\n| -------------------------------------------------------------------------- | ----------------------------------------- |\n| Generate HTML or tokens, validate a language, or manage a Wasm module | [Rendering](references/rendering.md) |\n| Load or customize themes, switch CSS variables, or render multiple schemes | [Themes](references/themes.md) |\n| Tokenize streamed strings or bytes | [Streaming](references/streaming.md) |\n| Apply edits, prioritize a viewport, or read packed token records | [Incremental editing](references/live.md) |\n\nFor file, diff, or editor components, read the [diffs skill](../diffs/SKILL.md).\n","frontmatter":{"name":"highlights","description":"Use when an app uses @pierre/highlights to generate syntax-highlighted HTML or tokens, stream code, incrementally tokenize edits, or apply Zed-compatible themes and CSS variables."},"isInternal":false,"tokens":319,"sizeBytes":1635},{"name":"INDEX.md","path":"skills/INDEX.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/INDEX.md","title":"Skills Skill","category":"anthropic-skill","format":"markdown","content":"# Pierre package skills\n\nUse these skills when an app or site consumes a Pierre package. Read the\nselected `SKILL.md` first. Load only the API or recipe reference that matches\nthe task.\n\n| Skill | Use it for |\n| --------------------------------- | --------------------------------------------------------------------------------------------------- |\n| [diffs](diffs/SKILL.md) | Render or edit code files, diffs, patches, and merge conflicts with `@pierre/diffs`. |\n| [highlights](highlights/SKILL.md) | Generate HTML or themed tokens, stream code, and apply incremental edits with `@pierre/highlights`. |\n| [theme](theme/SKILL.md) | Select and load a Pierre syntax or editor theme from `@pierre/theme`. |\n| [theming](theming/SKILL.md) | Build runtime theme collections, resolvers, controllers, and color mappings with `@pierre/theming`. |\n| [trees](trees/SKILL.md) | Render and control an interactive file tree with `@pierre/trees`. |\n\n## Package relationship\n\n`@pierre/theme` supplies theme objects. `@pierre/theming` selects, resolves, and\nmaps those objects. `@pierre/diffs` and `@pierre/trees` render code and file\ntrees with the selected theme.\n\n`@pierre/highlights` generates standalone HTML or tokens using Zed-compatible\nthemes from `@pierre/highlights/themes`. Its theme objects use a different\nformat from the Shiki and VS Code themes in `@pierre/theme`.\n","isInternal":false,"tokens":333,"sizeBytes":1597},{"name":"api.md","path":"skills/theme/references/api.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/theme/references/api.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# `@pierre/theme` API reference\n\nThis reference lists every public package entry.\n\n## Main entry\n\n| Import | Export | Purpose |\n| --------------- | ------------ | ------------------------------------------- |\n| `@pierre/theme` | `themeNames` | Lists the ten theme names in package order. |\n\n## Theme entries\n\nEach entry has one default export. The export is an immutable Pierre theme\nobject.\n\n| Import | Theme name | Color scheme | Purpose |\n| ---------------------------------------------------- | -------------------------------------- | ------------ | ---------------------------------------------------- |\n| `@pierre/theme/pierre-light` | `pierre-light` | Light | Supplies the standard light theme. |\n| `@pierre/theme/pierre-dark` | `pierre-dark` | Dark | Supplies the standard dark theme. |\n| `@pierre/theme/pierre-light-soft` | `pierre-light-soft` | Light | Supplies the soft light theme. |\n| `@pierre/theme/pierre-dark-soft` | `pierre-dark-soft` | Dark | Supplies the soft dark theme. |\n| `@pierre/theme/pierre-light-vibrant` | `pierre-light-vibrant` | Light | Supplies the Display-P3 light theme. |\n| `@pierre/theme/pierre-dark-vibrant` | `pierre-dark-vibrant` | Dark | Supplies the Display-P3 dark theme. |\n| `@pierre/theme/pierre-light-protanopia-deuteranopia` | `pierre-light-protanopia-deuteranopia` | Light | Supplies the light red-green color-vision variant. |\n| `@pierre/theme/pierre-dark-protanopia-deuteranopia` | `pierre-dark-protanopia-deuteranopia` | Dark | Supplies the dark red-green color-vision variant. |\n| `@pierre/theme/pierre-light-tritanopia` | `pierre-light-tritanopia` | Light | Supplies the light blue-yellow color-vision variant. |\n| `@pierre/theme/pierre-dark-tritanopia` | `pierre-dark-tritanopia` | Dark | Supplies the dark blue-yellow color-vision variant. |\n\n## Raw theme entries\n\n`@pierre/theme/themes/*` exposes each generated JSON file. Replace `*` with a\ntheme file name, including `.json`.\n\n## Theme object\n\nEach default export has these immutable fields:\n\n| Field | Purpose |\n| --------------------- | ---------------------------------------------- |\n| `name` | Provides the stable theme identifier. |\n| `displayName` | Provides the label for a theme selector. |\n| `type` | Identifies the `light` or `dark` color scheme. |\n| `colors` | Maps VS Code workbench color keys to colors. |\n| `tokenColors` | Defines TextMate token styles. |\n| `semanticTokenColors` | Defines semantic token styles. |\n","isInternal":false,"tokens":649,"sizeBytes":3264},{"name":"recipe-editor.md","path":"skills/theme/references/recipe-editor.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/theme/references/recipe-editor.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Recipe: use a Pierre theme in an editor\n\n## VS Code or Cursor\n\n1. Install the **Pierre Theme** extension from the editor marketplace.\n2. Open the color theme selector.\n3. Select a `Pierre` theme.\n\n## Zed\n\n1. Install the **Pierre** extension from the Zed extension registry.\n2. Open the theme selector.\n3. Select a `Pierre` theme.\n\nThe editor extensions include the standard, soft, protanopia and deuteranopia,\nand tritanopia treatments.\n","isInternal":false,"tokens":111,"sizeBytes":439},{"name":"recipe-shiki.md","path":"skills/theme/references/recipe-shiki.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/theme/references/recipe-shiki.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Recipe: use a Pierre theme with Shiki\n\nInstall the package:\n\n```bash\npnpm add @pierre/theme shiki\n```\n\nImport the theme object and pass it to Shiki:\n\n```ts\nimport pierreDark from '@pierre/theme/pierre-dark';\nimport { codeToHtml } from 'shiki';\n\nconst html = await codeToHtml(source, {\n lang: 'typescript',\n theme: pierreDark,\n});\n```\n\nImport a matching light and dark pair when the app supports both color schemes.\nUse the `theming` skill when the user can change the active theme at runtime.\n","isInternal":false,"tokens":127,"sizeBytes":497},{"name":"variants.md","path":"skills/theme/references/variants.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/theme/references/variants.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Pierre theme variants\n\nSelect one treatment and use its light and dark entries as a pair.\n\n| Treatment | Light entry | Dark entry | Select it for |\n| --------------------------- | -------------------------------------- | ------------------------------------- | ----------------------------------------- |\n| Standard | `pierre-light` | `pierre-dark` | The default Pierre appearance. |\n| Soft | `pierre-light-soft` | `pierre-dark-soft` | A lower-contrast appearance. |\n| Vibrant | `pierre-light-vibrant` | `pierre-dark-vibrant` | Display-P3 output in Shiki or a web page. |\n| Protanopia and deuteranopia | `pierre-light-protanopia-deuteranopia` | `pierre-dark-protanopia-deuteranopia` | Red-green color-vision support. |\n| Tritanopia | `pierre-light-tritanopia` | `pierre-dark-tritanopia` | Blue-yellow color-vision support. |\n\nThe editor extensions include the eight sRGB themes. The vibrant themes use CSS\nDisplay-P3 color syntax and target web output.\n\nUse the standard pair unless the product specifies another treatment. Use the\nsame treatment for both color schemes.\n","isInternal":false,"tokens":271,"sizeBytes":1438},{"name":"SKILL.md","path":"skills/theme/SKILL.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/theme/SKILL.md","title":"theme","category":"anthropic-skill","format":"markdown","content":"---\nname: theme\ndescription:\n Use when an app needs a Pierre light or dark theme from @pierre/theme for\n Shiki, VS Code, Cursor, or Zed, including soft, vibrant, protanopia,\n deuteranopia, and tritanopia variants.\n---\n\n# `@pierre/theme`\n\nUse `@pierre/theme` for Pierre syntax and editor themes. The package supplies\nten immutable Shiki and VS Code theme objects.\n\nFor Zed-compatible themes used by `@pierre/highlights`, read the\n[highlights skill](../highlights/SKILL.md).\n\n## Install\n\n```bash\npnpm add @pierre/theme\n```\n\n## Select an API reference\n\n| Need | Reference |\n| --------------------------------------- | ---------------------------------------- |\n| List every package entry and export | [API reference](references/api.md) |\n| Compare all themes and select a variant | [Theme variants](references/variants.md) |\n\n## Select a recipe\n\n| Task | Recipe |\n| ----------------------------------- | ------------------------------------------------------- |\n| Load a Pierre theme in Shiki | [Use a theme with Shiki](references/recipe-shiki.md) |\n| Install a Pierre theme in an editor | [Use a theme in an editor](references/recipe-editor.md) |\n\nUse the `theming` skill when the app must switch themes at runtime or follow a\ncolor mode.\n","frontmatter":{"name":"theme","description":"Use when an app needs a Pierre light or dark theme from @pierre/theme for Shiki, VS Code, Cursor, or Zed, including soft, vibrant, protanopia, deuteranopia, and tritanopia variants."},"isInternal":false,"tokens":292,"sizeBytes":1406},{"name":"collections.md","path":"skills/theming/references/collections.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/theming/references/collections.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Collections API\n\nThis reference covers collection APIs from `@pierre/theming` and all exports\nfrom `@pierre/theming/themes`.\n\n## `@pierre/theming` exports\n\n| Export | Kind | Purpose |\n| --------------------------- | -------- | ------------------------------------------------------------------ |\n| `createThemeCollection` | Function | Creates an immutable ordered set of theme descriptors. |\n| `ThemeCollection` | Type | Defines collection queries, transforms, and resolver registration. |\n| `ThemeCollectionComparator` | Type | Compares two descriptors for `orderBy`. |\n| `ThemeCollectionEntry` | Type | Accepts one descriptor or collection source. |\n| `ThemeCollectionFilter` | Type | Filters by `collection` and `colorScheme`. |\n| `ThemeCollectionInput` | Type | Accepts one entry or an iterable of entries. |\n| `ThemeCollectionSource` | Type | Defines an object that returns theme descriptors. |\n| `ThemeDescriptor` | Type | Describes one named theme and its lazy loader. |\n| `createThemeCatalog` | Function | Creates a collection with default light and dark theme names. |\n| `ThemeCatalog` | Type | Adds default theme names to `ThemeCollection`. |\n\n## `ThemeDescriptor` fields\n\n| Field | Purpose |\n| ------------- | --------------------------------------- |\n| `name` | Stores the stable theme identifier. |\n| `load` | Loads the theme object. |\n| `colorScheme` | Labels the descriptor as light or dark. |\n| `collection` | Groups related themes. |\n| `displayName` | Supplies a user-facing label. |\n\n## `ThemeCollection` methods\n\n| Method | Purpose |\n| ------------------------ | ---------------------------------------------------- |\n| `getTheme(name)` | Gets one descriptor by name. |\n| `getThemes(filter?)` | Lists descriptors that match an optional filter. |\n| `getThemeNames(filter?)` | Lists names that match an optional filter. |\n| `hasTheme(name)` | Tests whether the collection has a name. |\n| `orderBy(compare)` | Returns a new collection in comparator order. |\n| `pick(names)` | Returns a new collection in the supplied name order. |\n| `registerInto(resolver)` | Adds every descriptor loader to a resolver. |\n\n## `ThemeCatalog` fields\n\n| Field | Purpose |\n| ----------------------- | ------------------------------ |\n| `defaultLightThemeName` | Names the initial light theme. |\n| `defaultDarkThemeName` | Names the initial dark theme. |\n\n## `@pierre/theming/themes` exports\n\n| Export | Kind | Purpose |\n| -------------------- | -------- | ----------------------------------------------------------------------------- |\n| `themes` | Value | Combines the Pierre and Shiki collections in stable order. |\n| `pierreThemes` | Value | Provides lazy descriptors for the ten Pierre themes. |\n| `shikiThemes` | Value | Provides lazy descriptors for the bundled Shiki themes. |\n| `createTheme` | Function | Creates a descriptor whose loader normalizes a raw Shiki or VS Code theme. |\n| `CreateThemeOptions` | Type | Defines the name, loader, and optional descriptor metadata for `createTheme`. |\n\nUse `createTheme` for a raw Shiki or VS Code theme. Use a `ThemeDescriptor`\ndirectly when the loader already returns a compatible `ThemeLike` object.\n","isInternal":false,"tokens":747,"sizeBytes":4011},{"name":"colors.md","path":"skills/theming/references/colors.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/theming/references/colors.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Colors API\n\nThis reference covers every export from `@pierre/theming/color`.\n\n## Exports\n\n| Export | Kind | Purpose |\n| ---------------------- | -------- | -------------------------------------------------------------- |\n| `normalizeThemeColors` | Function | Resolves the UI color fallback chains in a `ThemeLike` object. |\n| `colorUtils` | Object | Groups pure color checks and transforms. |\n\n`normalizeThemeColors(theme)` returns a memoized `ThemeLike` object. Use its\n`colors` map for the UI around syntax-highlighted code.\n\n## `colorUtils` methods\n\n| Method | Purpose |\n| ---------------------------------------------------- | -------------------------------------------------------------- |\n| `relativeLuminance(color)` | Calculates WCAG luminance for a hex color. |\n| `contrastRatio(a, b)` | Calculates the contrast ratio between two luminance values. |\n| `compositeOverBg(foreground, background?)` | Flattens a translucent hex color over a background. |\n| `isFullyTransparent(color?)` | Tests whether a hex color has zero alpha. |\n| `isDarkSurface(background?, foregroundHint?)` | Classifies a surface as dark or light. |\n| `surfacesMatch(a?, b?)` | Tests whether two hex surfaces produce the same visible color. |\n| `hoverWouldEraseText(hover, background, foreground)` | Tests whether a hover surface removes text contrast. |\n| `pickReadableForeground(background, candidates)` | Selects the candidate with the best readable contrast. |\n| `deriveMutedFg(foreground, background)` | Derives a muted foreground with readable contrast. |\n\nThe color methods measure hex colors. A method returns its documented empty\nresult when it cannot measure another CSS color format.\n","isInternal":false,"tokens":377,"sizeBytes":2139},{"name":"controller.md","path":"skills/theming/references/controller.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/theming/references/controller.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Controller API\n\nThis reference covers controller and shared theme types from `@pierre/theming`.\n\n## Exports\n\n| Export | Kind | Purpose |\n| ----------------------------- | -------- | ------------------------------------------------------------------ |\n| `createThemeController` | Function | Creates state for a color mode and selected light and dark themes. |\n| `ThemeController` | Type | Defines controller state, mutations, subscription, and cleanup. |\n| `ThemeControllerOptions` | Type | Selects a catalog or resolver and configures initial state. |\n| `ThemeControllerState` | Type | Describes the current selection and resolved theme. |\n| `PendingThemeResolution` | Type | Identifies the active theme load. |\n| `ThemeResolutionError` | Type | Describes a failed active theme load. |\n| `ThemeResolutionErrorContext` | Type | Identifies the name and scheme for a failed load callback. |\n| `ThemePersistence` | Type | Defines custom `load` and `save` methods. |\n| `ThemeSelection` | Type | Describes the persisted mode and theme names. |\n| `ColorMode` | Type | Accepts `light`, `dark`, or `system`. |\n| `ColorScheme` | Type | Accepts concrete `light` or `dark`. |\n| `ThemeLike` | Type | Defines the shared resolved-theme shape. |\n\n## `ThemeControllerOptions` fields\n\n| Field | Purpose |\n| ----------------------- | ------------------------------------------------------------------- |\n| `catalog` | Supplies descriptors and catalog default names. |\n| `resolver` | Supplies an existing resolver or shares one with other controllers. |\n| `defaultLightThemeName` | Overrides the initial light theme name. |\n| `defaultDarkThemeName` | Overrides the initial dark theme name. |\n| `defaultMode` | Sets the initial color mode. |\n| `storageKey` | Stores the selection in browser local storage. |\n| `persistence` | Supplies custom selection storage. |\n| `preloadInactive` | Resolves the inactive color-scheme theme too. |\n| `onResolutionError` | Receives an active theme load error. |\n\nPass a `catalog`, a `resolver`, or a catalog with a shared resolver.\n\n## `ThemeController` members\n\n| Member | Purpose |\n| ------------------------------------- | ---------------------------------------------------------------- |\n| `resolver` | Exposes the controller's resolver. |\n| `getState()` | Returns the current immutable state object. |\n| `setColorMode(mode)` | Selects light, dark, or system mode. |\n| `setThemeNameForScheme(scheme, name)` | Selects the theme for one color scheme. |\n| `subscribe(listener)` | Subscribes to state changes and returns an unsubscribe function. |\n| `destroy()` | Removes the system color-scheme listener. |\n\n## `ThemeControllerState` fields\n\n| Field | Purpose |\n| ------------------------ | -------------------------------------------------- |\n| `lightThemeName` | Stores the selected light theme name. |\n| `darkThemeName` | Stores the selected dark theme name. |\n| `mode` | Stores the selected color mode. |\n| `resolvedColorScheme` | Provides the active concrete light or dark scheme. |\n| `resolvedTheme` | Provides the active resolved theme object. |\n| `pendingThemeResolution` | Identifies an active theme load. |\n| `resolutionError` | Describes the latest active load failure. |\n","isInternal":false,"tokens":769,"sizeBytes":4568},{"name":"react.md","path":"skills/theming/references/react.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/theming/references/react.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# React API\n\nThis reference lists every export from `@pierre/theming/react`.\n\n| Export | Kind | Purpose |\n| -------------------- | ---- | ------------------------------------------------------------------------- |\n| `useThemeController` | Hook | Subscribes to a `ThemeController` and returns its `ThemeControllerState`. |\n\nThe hook uses the controller state for both client and server snapshots. Create\nthe controller outside the component that reads it.\n","isInternal":false,"tokens":85,"sizeBytes":535},{"name":"recipe-multiple-controllers.md","path":"skills/theming/references/recipe-multiple-controllers.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/theming/references/recipe-multiple-controllers.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Recipe: use multiple theme controllers\n\nUse multiple controllers when independent areas need different modes,\nselections, storage, or lifecycles. Share one resolver when those areas use the\nsame theme loaders and cache.\n\n```ts\nimport {\n createThemeCatalog,\n createThemeController,\n createThemeResolver,\n} from '@pierre/theming';\nimport { themes } from '@pierre/theming/themes';\n\nconst catalog = createThemeCatalog({\n themes,\n defaultLightThemeName: 'pierre-light',\n defaultDarkThemeName: 'pierre-dark',\n});\n\nconst resolver = createThemeResolver();\n\nexport const workspaceTheme = createThemeController({\n catalog,\n resolver,\n storageKey: 'workspace-theme',\n});\n\nexport const previewTheme = createThemeController({\n catalog,\n resolver,\n defaultMode: 'light',\n storageKey: 'preview-theme',\n});\n```\n\nSubscribe each area to its own controller. Call `destroy()` on each controller\nwhen its area is removed. Use distinct storage keys when selections must remain\nindependent.\n","isInternal":false,"tokens":214,"sizeBytes":983},{"name":"recipe-one-controller.md","path":"skills/theming/references/recipe-one-controller.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/theming/references/recipe-one-controller.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Recipe: use one theme controller\n\nUse one controller when the app shares one color mode and one light/dark theme\nselection.\n\nCreate the catalog and controller in one module:\n\n```ts\nimport { createThemeCatalog, createThemeController } from '@pierre/theming';\nimport { themes } from '@pierre/theming/themes';\n\nexport const themeCatalog = createThemeCatalog({\n themes,\n defaultLightThemeName: 'pierre-light',\n defaultDarkThemeName: 'pierre-dark',\n});\n\nexport const themeController = createThemeController({\n catalog: themeCatalog,\n defaultMode: 'system',\n storageKey: 'app-theme',\n});\n```\n\nImport the same controller wherever the app reads or changes theme state. Call\n`destroy()` when the application tears down the controller module.\n","isInternal":false,"tokens":163,"sizeBytes":741},{"name":"recipe-react.md","path":"skills/theming/references/recipe-react.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/theming/references/recipe-react.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Recipe: use a theme controller in React\n\nCreate the controller in a module. Read it with `useThemeController`:\n\n```tsx\nimport { useEffect } from 'react';\nimport { useThemeController } from '@pierre/theming/react';\n\nimport { themeController } from './theme-controller';\n\nexport function ThemeControls() {\n const state = useThemeController(themeController);\n\n useEffect(() => {\n document.documentElement.dataset.colorScheme = state.resolvedColorScheme;\n }, [state.resolvedColorScheme]);\n\n return (\n \n themeController.setColorMode(\n state.resolvedColorScheme === 'dark' ? 'light' : 'dark'\n )\n }\n >\n Use {state.resolvedColorScheme === 'dark' ? 'light' : 'dark'} mode\n \n );\n}\n```\n\nPass `state.resolvedTheme` to code or tree surfaces. Use `normalizeThemeColors`\nwhen a React component needs workbench UI colors.\n","isInternal":false,"tokens":210,"sizeBytes":915},{"name":"recipe-vanilla.md","path":"skills/theming/references/recipe-vanilla.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/theming/references/recipe-vanilla.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Recipe: use a theme controller in vanilla JavaScript\n\nCreate a controller with the one-controller or multiple-controller recipe. Apply\neach state change to the document:\n\n```ts\nimport { normalizeThemeColors } from '@pierre/theming/color';\nimport { themeController } from './theme-controller';\n\nfunction applyTheme() {\n const state = themeController.getState();\n document.documentElement.dataset.colorScheme = state.resolvedColorScheme;\n\n if (state.resolvedTheme == null) return;\n const { colors } = normalizeThemeColors(state.resolvedTheme);\n document.documentElement.style.setProperty(\n '--app-background',\n colors?.['editor.background'] ?? state.resolvedTheme.bg ?? ''\n );\n document.documentElement.style.setProperty(\n '--app-foreground',\n colors?.['editor.foreground'] ?? state.resolvedTheme.fg ?? ''\n );\n}\n\napplyTheme();\nconst unsubscribe = themeController.subscribe(applyTheme);\n```\n\nCall `themeController.setColorMode(mode)` from a mode control. Call\n`setThemeNameForScheme(scheme, name)` from a theme selector. Call\n`unsubscribe()` when the host no longer needs updates.\n","isInternal":false,"tokens":230,"sizeBytes":1100},{"name":"resolver.md","path":"skills/theming/references/resolver.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/theming/references/resolver.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Resolver API\n\nThis reference covers the resolver exports from `@pierre/theming`.\n\n## Exports\n\n| Export | Kind | Purpose |\n| ------------------------ | -------- | ------------------------------------------------------------- |\n| `createThemeResolver` | Function | Creates an isolated loader registry and resolved-theme cache. |\n| `ThemeResolver` | Type | Defines the resolver methods. |\n| `ThemeLoader` | Type | Defines an asynchronous theme loader. |\n| `DuplicateThemeError` | Class | Reports a second registration for the same name. |\n| `UnregisteredThemeError` | Class | Reports a resolve request for a name with no loader. |\n| `UnresolvedThemeError` | Class | Reports a synchronous batch read with an unresolved name. |\n\n## `ThemeResolver` methods\n\n| Method | Purpose |\n| ------------------------------------- | -------------------------------------------------------- |\n| `registerTheme(name, loader)` | Registers one loader. |\n| `registerThemeIfAbsent(name, loader)` | Registers one loader only when the name is free. |\n| `hasRegisteredTheme(name)` | Tests whether a loader exists. |\n| `resolveTheme(name)` | Loads and caches one theme. |\n| `resolveThemes(names)` | Loads and caches themes in input order. |\n| `getResolvedTheme(name)` | Reads one cached theme or returns `undefined`. |\n| `getResolvedThemes(names)` | Reads cached themes in input order. |\n| `getResolvedOrResolveTheme(name)` | Returns a cached theme or starts its load. |\n| `hasResolvedTheme(name)` | Tests whether one cached theme exists. |\n| `hasResolvedThemes(names)` | Tests whether all named themes exist in the cache. |\n| `seedResolvedTheme(name, theme)` | Adds one resolved object without a loader. |\n| `seedResolvedThemes(entries)` | Adds several resolved objects without loaders. |\n| `clearResolvedThemes()` | Clears cached themes and active loads but keeps loaders. |\n\nEach loader returns a `ThemeLike` object or a module object with that value on\n`default`.\n\n## Fallback loading and normalization\n\n`createThemeResolver(options?)` accepts `ThemeResolverOptions`:\n\n```ts\nconst resolver = createThemeResolver({\n fallbackLoader: async (name) => {\n const loader = bundledLoaders[name];\n return loader === undefined ? undefined : loader();\n },\n normalizeTheme: (theme, name) => ({ ...theme, name }),\n});\n```\n\nExplicit registrations take precedence over `fallbackLoader`. A fallback may\nreturn a theme, a `{ default: theme }` module, or `undefined` for an unknown\nname. `normalizeTheme(theme, name)` can be synchronous or asynchronous and runs\nbefore successful loads enter the cache. Seeded values are already normalized.\nConcurrent calls share fallback loading and normalization; rejected loads can be\nretried. Clearing caches prevents an earlier in-flight load from repopulating\nthem. The core resolver still imports no backend or bundled theme data.\n","isInternal":false,"tokens":653,"sizeBytes":3477},{"name":"SKILL.md","path":"skills/theming/SKILL.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/theming/SKILL.md","title":"theming","category":"anthropic-skill","format":"markdown","content":"---\nname: theming\ndescription:\n Use when an app uses @pierre/theming to list, resolve, select, switch,\n persist, or apply themes, including color modes, theme controllers, React\n state, UI colors, and bundled Pierre or Shiki collections.\n---\n\n# `@pierre/theming`\n\nUse `@pierre/theming` to manage runtime themes. The package separates theme\nmetadata, theme resolution, selected state, and UI color mapping.\n\n## Install\n\n```bash\npnpm add @pierre/theming\n```\n\nInstall optional peer dependencies only for the selected entry. The React entry\nneeds `react`. The themes entry needs `@pierre/theme`, `@shikijs/themes`, and\n`shiki`.\n\n## Select an API reference\n\n| Need | Reference |\n| -------------------------------------------------------------- | -------------------------------------------- |\n| Create a collection, catalog, descriptor, or bundled theme set | [Collections API](references/collections.md) |\n| Register, load, seed, or cache theme objects | [Resolver API](references/resolver.md) |\n| Track the color mode and selected light and dark themes | [Controller API](references/controller.md) |\n| Normalize workbench colors or derive colors | [Colors API](references/colors.md) |\n| Read controller state in React | [React API](references/react.md) |\n\n## Select a controller recipe\n\n| Situation | Recipe |\n| ---------------------------------------------------------------------------- | --------------------------------------------------------------------- |\n| One app or page shares one color mode and one light/dark selection | [Use one controller](references/recipe-one-controller.md) |\n| Independent areas need separate selections or separate controller lifecycles | [Use multiple controllers](references/recipe-multiple-controllers.md) |\n\nUse one controller by default. Use multiple controllers only when the theme\nstate must differ between areas.\n\n## Select a framework recipe\n\n| Host | Recipe |\n| --------------------------------------- | ------------------------------------------------------ |\n| Vanilla JavaScript or another framework | [Use vanilla JavaScript](references/recipe-vanilla.md) |\n| React | [Use React](references/recipe-react.md) |\n","frontmatter":{"name":"theming","description":"Use when an app uses @pierre/theming to list, resolve, select, switch, persist, or apply themes, including color modes, theme controllers, React state, UI colors, and bundled Pierre or Shiki collections."},"isInternal":false,"tokens":440,"sizeBytes":2643},{"name":"api-core.md","path":"skills/trees/references/api-core.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/trees/references/api-core.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Core API\n\nThis reference lists every export from `@pierre/trees` and every public\n`FileTree` member.\n\n## Contents\n\n- [Runtime values](#runtime-values)\n- [`FileTree` members](#filetree-members)\n- [Configuration and state types](#configuration-and-state-types)\n- [Mutation types](#mutation-types)\n- [Interaction types](#interaction-types)\n- [Presentation types](#presentation-types)\n- [Constants](#constants)\n\n## Runtime values\n\n| Export | Kind | Purpose |\n| ------------------------------- | -------- | ----------------------------------------------------------------- |\n| `FileTree` | Class | Owns the tree model, renders it, and exposes path-based controls. |\n| `prepareFileTreeInput` | Function | Prepares and optionally sorts a path list for reuse. |\n| `preparePresortedFileTreeInput` | Function | Prepares a path list that already has final order. |\n| `preloadFileTree` | Function | Creates server-rendered tree markup and hydration data. |\n| `serializeFileTreeSsrPayload` | Function | Joins an SSR payload into one host markup string. |\n| `themeToTreeStyles` | Function | Maps a resolved theme to tree host CSS properties. |\n| `getBuiltInSpriteSheet` | Function | Gets the SVG sprite for a built-in icon set. |\n| `createFileTreeIconResolver` | Function | Creates an icon resolver from an icon configuration. |\n\n## `FileTree` members\n\n| Member | Purpose |\n| -------------------------------- | ----------------------------------------------------------- |\n| `new FileTree(options)` | Creates a model from paths or prepared input. |\n| `FileTree.LoadedCustomComponent` | Reports whether the file-tree custom element module loaded. |\n| `render(props)` | Mounts the tree into a wrapper or host element. |\n| `hydrate(props)` | Attaches the model to preloaded host markup. |\n| `unmount()` | Removes the mounted view and keeps the model. |\n| `cleanUp()` | Removes the view and destroys model resources. |\n| `getFileTreeContainer()` | Gets the mounted host element. |\n| `getItem(path)` | Gets a path handle or `null`. |\n| `getFocusedItem()` | Gets the focused item handle or `null`. |\n| `getFocusedPath()` | Gets the focused path or `null`. |\n| `getSelectedPaths()` | Gets the selected paths. |\n| `getComposition()` | Gets the current header and context-menu configuration. |\n| `getItemHeight()` | Gets the resolved row height. |\n| `getDensityFactor()` | Gets the resolved density factor. |\n| `subscribe(listener)` | Subscribes to model changes. |\n| `focusPath(path)` | Focuses a path. |\n| `focusNearestPath(path)` | Focuses and returns the nearest available path. |\n| `scrollToPath(path, options?)` | Scrolls a path into view. |\n| `add(path)` | Adds one path. |\n| `remove(path, options?)` | Removes one path. |\n| `move(from, to, options?)` | Moves one path. |\n| `batch(operations)` | Applies several path mutations together. |\n| `resetPaths(paths, options?)` | Replaces the full path set. |\n| `onMutation(type, handler)` | Subscribes to mutation events. |\n| `setSearch(value)` | Sets or clears the search query. |\n| `openSearch(initialValue?)` | Opens the search session. |\n| `closeSearch()` | Closes the search session. |\n| `isSearchOpen()` | Tests whether search is open. |\n| `getSearchValue()` | Gets the search query. |\n| `getSearchMatchingPaths()` | Gets paths that match the query. |\n| `focusNextSearchMatch()` | Focuses the next search match. |\n| `focusPreviousSearchMatch()` | Focuses the previous search match. |\n| `startRenaming(path?, options?)` | Starts inline rename and reports whether it started. |\n| `setGitStatus(status?)` | Replaces all git status entries. |\n| `applyGitStatusPatch(patch)` | Applies a partial git status update. |\n| `setIcons(icons?)` | Replaces the icon configuration. |\n| `setComposition(composition?)` | Replaces header and context-menu configuration. |\n\n## Configuration and state types\n\n| Export | Purpose |\n| -------------------------- | --------------------------------------------------------------- |\n| `FileTreeOptions` | Defines input, behavior, rendering, and presentation options. |\n| `FileTreePreparedInput` | Holds a reusable prepared path list. |\n| `FileTreeInitialExpansion` | Selects closed, open, or depth-based initial expansion. |\n| `FileTreeSortComparator` | Compares two path entries. |\n| `FileTreeSortEntry` | Describes one path for a sort comparator. |\n| `FileTreeRenderOptions` | Configures row height, row count, overscan, and sticky folders. |\n| `FileTreeRenderProps` | Selects the wrapper or existing host for `render`. |\n| `FileTreeHydrationProps` | Selects the host for `hydrate`. |\n| `FileTreeVisibleRow` | Describes one visible tree row. |\n| `FileTreeItemHandle` | Represents a file or directory item. |\n| `FileTreeFileHandle` | Controls one file item. |\n| `FileTreeDirectoryHandle` | Controls one directory item and its expansion. |\n| `FileTreeListener` | Defines a model subscription callback. |\n| `FileTreeSsrPayload` | Holds the host and shadow markup for server output. |\n\n## Mutation types\n\n| Export | Purpose |\n| ----------------------------------- | -------------------------------------------------------------- |\n| `FileTreeMutationHandle` | Defines the public path mutation methods. |\n| `FileTreeBatchOperation` | Describes one add, remove, or move in a batch. |\n| `FileTreeCollisionStrategy` | Selects error, replace, or skip behavior for a move collision. |\n| `FileTreeMoveOptions` | Configures move collision behavior. |\n| `FileTreeRemoveOptions` | Configures recursive removal. |\n| `FileTreeResetOptions` | Configures a path reset and optional prepared input. |\n| `FileTreeResetPreparedOptions` | Configures a reset that uses prepared input. |\n| `FileTreeMutationEvent` | Represents any mutation event. |\n| `FileTreeMutationSemanticEvent` | Represents an add, remove, move, or reset event. |\n| `FileTreeMutationEventType` | Names a mutation operation. |\n| `FileTreeMutationEventForType` | Selects the event shape for an operation name. |\n| `FileTreeMutationEventInvalidation` | Describes the state invalidation from a mutation. |\n| `FileTreeAddEvent` | Describes one add result. |\n| `FileTreeRemoveEvent` | Describes one remove result. |\n| `FileTreeMoveEvent` | Describes one move result. |\n| `FileTreeResetEvent` | Describes one reset result. |\n| `FileTreeBatchEvent` | Describes one batch result. |\n\n## Interaction types\n\n| Export | Purpose |\n| --------------------------------- | -------------------------------------------------- |\n| `FileTreeSelectionChangeListener` | Receives the selected path list. |\n| `FileTreeSearchChangeListener` | Receives the current search query. |\n| `FileTreeSearchSessionHandle` | Defines search session methods. |\n| `FileTreeSearchMode` | Selects how nonmatching rows appear. |\n| `FileTreeSearchBlurBehavior` | Selects search behavior after focus leaves. |\n| `FileTreeScrollOffset` | Selects top, center, or nearest scroll alignment. |\n| `FileTreeScrollToPathOptions` | Configures focus and alignment for `scrollToPath`. |\n| `FileTreeDragAndDropConfig` | Configures drag rules and completion callbacks. |\n| `FileTreeDropTarget` | Describes the current drop target. |\n| `FileTreeDropContext` | Describes dragged paths and their target. |\n| `FileTreeDropResult` | Describes the completed move or batch operation. |\n| `FileTreeRenamingConfig` | Configures rename rules and callbacks. |\n| `FileTreeRenamingItem` | Describes the item offered to a rename rule. |\n| `FileTreeRenameEvent` | Describes a completed rename. |\n\n## Presentation types\n\n| Export | Purpose |\n| ---------------------------------- | ----------------------------------------------------------- |\n| `FileTreeCompositionOptions` | Configures header and context-menu composition. |\n| `FileTreeHeaderCompositionOptions` | Supplies header HTML or a header renderer. |\n| `ContextMenuItem` | Describes the file or directory for a context menu. |\n| `ContextMenuOpenContext` | Supplies menu position, close, and focus controls. |\n| `ContextMenuAnchorRect` | Describes the menu anchor rectangle. |\n| `ContextMenuTriggerMode` | Selects right-click, button, or both triggers. |\n| `ContextMenuButtonVisibility` | Selects when the row menu button appears. |\n| `FileTreeRowDecoration` | Describes text or icon content in the decoration lane. |\n| `FileTreeRowDecorationContext` | Supplies the item and visible row to a decoration renderer. |\n| `FileTreeRowDecorationRenderer` | Produces one row decoration. |\n| `GitStatus` | Names a supported git status. |\n| `GitStatusEntry` | Assigns a git status to one path. |\n| `FileTreeGitStatusPatch` | Adds, changes, or removes git status entries. |\n| `FileTreeBuiltInIconSet` | Names a built-in icon set. |\n| `FileTreeIconConfig` | Configures built-in and custom icon rules. |\n| `FileTreeIcons` | Accepts an icon set name or icon configuration. |\n| `RemappedIcon` | Names or defines a replacement SVG symbol. |\n| `FileTreeDensity` | Accepts a density keyword or numeric factor. |\n| `FileTreeDensityKeyword` | Names compact, default, or relaxed density. |\n| `FileTreeDensityPreset` | Holds a density factor and row height. |\n| `TreeThemeInput` | Defines the resolved theme accepted by `themeToTreeStyles`. |\n| `TreeThemeStyles` | Maps tree CSS property names to values. |\n\n## Constants\n\n| Export | Purpose |\n| ---------------------------------------------- | --------------------------------------------------------------- |\n| `FILE_TREE_TAG_NAME` | Provides the `file-tree-container` element name. |\n| `FILE_TREE_STYLE_ATTRIBUTE` | Provides the core style marker attribute. |\n| `FILE_TREE_UNSAFE_CSS_ATTRIBUTE` | Provides the custom style marker attribute. |\n| `FILE_TREE_SCROLLBAR_MEASURE_ATTRIBUTE` | Provides the scrollbar measurement attribute. |\n| `FILE_TREE_SCROLLBAR_GUTTER_STYLE_ATTRIBUTE` | Provides the measured scrollbar style attribute. |\n| `FILE_TREE_SCROLLBAR_GUTTER_MEASURED_PROPERTY` | Provides the measured scrollbar CSS property. |\n| `FILE_TREE_DEFAULT_ITEM_HEIGHT` | Provides the default row height. |\n| `FILE_TREE_DENSITY_PRESETS` | Maps each density keyword to its preset. |\n| `FLATTENED_PREFIX` | Provides the identifier prefix for a flattened directory chain. |\n| `HEADER_SLOT_NAME` | Provides the header slot name. |\n| `CONTEXT_MENU_SLOT_NAME` | Provides the context-menu slot name. |\n| `CONTEXT_MENU_TRIGGER_TYPE` | Provides the context-menu trigger type. |\n","isInternal":false,"tokens":2623,"sizeBytes":14646},{"name":"api-react.md","path":"skills/trees/references/api-react.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/trees/references/api-react.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# React API\n\nThis reference lists every export from `@pierre/trees/react`.\n\n| Export | Kind | Purpose |\n| -------------------------- | --------- | ---------------------------------------------------------------------- |\n| `FileTree` | Component | Mounts a `FileTree` model in a React host element. |\n| `FileTreeProps` | Type | Defines the model, header, context menu, preload data, and host props. |\n| `FileTreePreloadedData` | Type | Selects the `id` and `shadowHtml` fields for hydration. |\n| `useFileTree` | Hook | Creates one stable `FileTree` model. |\n| `UseFileTreeResult` | Type | Holds the model returned by `useFileTree`. |\n| `useFileTreeSelection` | Hook | Returns the selected path list and updates with the model. |\n| `useFileTreeSearch` | Hook | Returns search state and search actions. |\n| `FileTreeSearchState` | Type | Defines the search snapshot and actions. |\n| `useFileTreeSelector` | Hook | Subscribes to a selected part of model state. |\n| `FileTreeSelector` | Type | Selects a value from a model. |\n| `FileTreeSelectorEquality` | Type | Compares two selected values. |\n\n`FileTreeProps` extends React host attributes except `children`. Its specific\nfields are:\n\n| Field | Purpose |\n| ------------------- | --------------------------------------------------- |\n| `model` | Supplies the required `FileTree` model. |\n| `header` | Supplies React content for the header slot. |\n| `renderContextMenu` | Produces React content for the active context menu. |\n| `preloadedData` | Supplies server markup for hydration. |\n","isInternal":false,"tokens":397,"sizeBytes":2144},{"name":"api-ssr.md","path":"skills/trees/references/api-ssr.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/trees/references/api-ssr.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# SSR API\n\nThis reference lists every export from `@pierre/trees/ssr`.\n\n| Export | Kind | Purpose |\n| ----------------------------- | -------- | --------------------------------------------------------------- |\n| `preloadFileTree` | Function | Renders a tree to a `FileTreeSsrPayload`. |\n| `serializeFileTreeSsrPayload` | Function | Creates declarative or DOM-inserted host markup from a payload. |\n| `FileTreeSsrPayload` | Type | Holds the host start, shadow HTML, host end, and stable ID. |\n\n`preloadFileTree` and `serializeFileTreeSsrPayload` are also available from\n`@pierre/trees`.\n","isInternal":false,"tokens":144,"sizeBytes":721},{"name":"api-web-components.md","path":"skills/trees/references/api-web-components.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/trees/references/api-web-components.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Web components API\n\nImport `@pierre/trees/web-components` to register the `file-tree-container`\ncustom element. The entry exports these APIs:\n\n| Export | Kind | Purpose |\n| --------------------------- | -------- | ------------------------------------------------------------------------- |\n| `FileTreeContainerLoaded` | Value | Confirms that the registration module ran. |\n| `adoptDeclarativeShadowDom` | Function | Copies a declarative template into an empty shadow root. |\n| `ensureFileTreeStyles` | Function | Installs the core tree stylesheet in a shadow root. |\n| `prepareFileTreeShadowRoot` | Function | Adopts server markup, installs styles, and measures the scrollbar gutter. |\n","isInternal":false,"tokens":147,"sizeBytes":859},{"name":"recipe-interactions.md","path":"skills/trees/references/recipe-interactions.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/trees/references/recipe-interactions.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"","isInternal":false,"tokens":169,"sizeBytes":710},{"name":"recipe-react.md","path":"skills/trees/references/recipe-react.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/trees/references/recipe-react.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"","isInternal":false,"tokens":133,"sizeBytes":546},{"name":"recipe-ssr.md","path":"skills/trees/references/recipe-ssr.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/trees/references/recipe-ssr.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"","isInternal":false,"tokens":202,"sizeBytes":789},{"name":"recipe-theme.md","path":"skills/trees/references/recipe-theme.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/trees/references/recipe-theme.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"","isInternal":false,"tokens":117,"sizeBytes":488},{"name":"recipe-vanilla.md","path":"skills/trees/references/recipe-vanilla.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/trees/references/recipe-vanilla.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"","isInternal":false,"tokens":150,"sizeBytes":597},{"name":"SKILL.md","path":"skills/trees/SKILL.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/skills/trees/SKILL.md","title":"trees","category":"anthropic-skill","format":"markdown","content":"","frontmatter":{"name":"trees","description":"Use when an app uses @pierre/trees to render or control a file tree, including React, vanilla JavaScript, SSR, web components, selection, search, rename, drag and drop, icons, git status, and themes."},"isInternal":false,"tokens":377,"sizeBytes":1891},{"name":"README.md","path":"packages/diffs/README.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/packages/diffs/README.md","title":"diffs Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":555,"sizeBytes":2269},{"name":"README.md","path":"packages/diffs/test/README.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/packages/diffs/test/README.md","title":"test Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":1397,"sizeBytes":5904},{"name":"README.md","path":"packages/highlights/benchmark/README.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/packages/highlights/benchmark/README.md","title":"benchmark Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":4182,"sizeBytes":14240},{"name":"README.md","path":"packages/highlights/README.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/packages/highlights/README.md","title":"highlights Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":374,"sizeBytes":1456},{"name":"README.md","path":"packages/highlights/themes/README.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/packages/highlights/themes/README.md","title":"themes Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":2155,"sizeBytes":9595},{"name":"README.md","path":"packages/path-store/README.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/packages/path-store/README.md","title":"path-store Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":472,"sizeBytes":2139},{"name":"README.md","path":"packages/pipes/README.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/packages/pipes/README.md","title":"pipes Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":1248,"sizeBytes":4621},{"name":"README.md","path":"packages/theme/README.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/packages/theme/README.md","title":"theme Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":492,"sizeBytes":1767},{"name":"README.md","path":"packages/theme/zed/README.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/packages/theme/zed/README.md","title":"zed Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":202,"sizeBytes":700},{"name":"README.md","path":"packages/theming/README.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/packages/theming/README.md","title":"theming Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":5414,"sizeBytes":23734},{"name":"README.md","path":"packages/trees/README.md","rawUrl":"https://raw.githubusercontent.com/pierrecomputer/pierre/HEAD/packages/trees/README.md","title":"trees Documentation","category":"plugin-manifest","format":"markdown","content":"","isInternal":false,"tokens":1509,"sizeBytes":5899}],"systemPromptSnippet":"\n\n# PierreJS Monorepo\n\n## Agent Environment\n\nSet `AGENT=1` at the start of every terminal session so Bun's test runner emits\nAI-friendly output:\n\n```bash\nexport AGENT=1\n```\n\nMost local moon tasks (formatters, benchmarks, worktree management) are\nconfigured with `runInCI: 'always'` so they keep working in CI-marked shells\nlike agent harnesses. Tasks connected to the build graph (dev servers, prod\nserves, e2e variants, publish guards) stay CI-skipped — run those with\n`moonx --ignore-ci-checks`, e.g.\n`moonx docs:dev-diffs --ignore-ci-checks`. For non-moon commands that CI-gate\nthemselves, unset the var: `CI= pnpm publish --dry-run`.\n\n## Toolchain\n\n- Tool versions (bun, pnpm, node, moon, gh) are pinned in `.prototools` and\n managed by [proto](https://moonrepo.dev/docs/proto); run `proto use` if a tool\n is missing or a pin changed. Never install toolchain versions globally; bump\n pins only in `.prototools`.\n- [moon](https://moonrepo.dev/docs) is the task runner; `package.json` scripts\n are npm lifecycle hooks only.\n\n## Core Rules\n\n- Use `pnpm` for install/add/remove/dedupe/package-manager and publishing work.\n Do not use `bun`, `npm`, `yarn`, `npx`, or similar tools for package\n operations unless there is a specific reason.\n- Dependencies use the `catalog` in `pnpm-workspace.yaml`. Never add dependency\n versions directly to package-level `package.json` files unless a published\n package intentionally needs its own range.\n- Run tasks through moon: `moon run :` (or the `moonx` shorthand)\n works from anywhere in the repo. `moonx : -- args` forwards\n arguments. Discover tasks with `moon tasks `.\n- Preserve trailing newlines at the end of files.\n- Setup steps for a fresh clone live in `CONTRIBUTING.md`.\n\n## Licensing\n\nEvery package in this repo is licensed under Apache 2.0. When adding a new\npackage under `packages/*` or `apps/*`:\n\n- Set `\"license\": \"apache-2.0\"` in its `package.json`.\n- Add an Apache 2.0 `LICENSE.md` at the package root — copy one from an existing\n package (e.g. `packages/trees/LICENSE.md`).\n\nVendored third-party code keeps its original license; record that attribution in\na `NOTICE.md` next to the package rather than changing its LICENSE.\n\n`moon run root:check-licenses` enforces both requirements and runs in CI on\nevery PR.\n\n## Skills\n\nDomain-specific context and conventions live in `.agents/skills/`. Before\nstarting any task:\n\n1. List `.agents/skills/*/SKILL.md`\n2. Read only each skill's frontmatter description to identify relevant skills\n3. Read only the full `SKILL.md` files relevant to your task\n\nDo not load skills that are not relevant to the task.\n\n## Agent Artifacts\n\nWrite agent-only planning and scratch artifacts under `.agents/ignore/` by\ndefault:\n\n- Plans: `.agents/ignore/plans/YYYY-MM-DD-.md`\n- Specs: `.agents/ignore/specs/YYYY-MM-DD-.md`\n\n`.agents/ignore/` is gitignored. Do not put source files, tests, or committed\ndocumentation there.\n\n## Verification Baseline\n\nAfter code changes, verification is not complete until you have run these from\nanywhere in the repo:\n\n```bash\nmoon run root:format root:lint\n```\n\nAlso run the affected typecheck and focused tests for the changed area, e.g.\n`moonx :typecheck` and `moonx :test` (or\n`moonx :typecheck --affected`). For docs-only or AGENTS/skill-only changes,\nformatting and linting are sufficient unless the edit touches executable code or\npackage config.\n\n## Code Readability\n\n- When adding non-trivial helpers, prefer a short comment directly above the\n function explaining what the helper does and why it exists.\n- Write comments for readers new to the codepath. Avoid vague shorthand like\n \"snapshot\" unless you immediately explain what data is captured or derived.\n- Prefer function-level comments over many inline comments. Use inline comments\n only when a specific step is still non-obvious.\n- Keep comments concrete and behavior-focused.\n\n\n@AGENTS.md\n\n\n---\nname: browser-automation\ndescription:\n Use when opening, inspecting, clicking, filling, snapshotting, or otherwise\n automating web pages for this repo, including local dev servers and\n browser-based verification.\n---\n\n# Browser Automation\n\nUse `agent-browser` for web automation in this repo. Run:\n\n```bash\nagent-browser --help\n```\n\nCore workflow:\n\n```bash\nagent-browser open \nagent-browser snapshot -i\nagent-browser click @e1\nagent-browser fill @e2 \"text\"\n```\n\nRe-run `agent-browser snapshot -i` after page changes so element refs stay\ncurrent.\n\nUse browser automation for behavior that needs a rendered page, real DOM state,\nor interactive verification. Prefer focused Bun tests for pure logic and\nnon-browser integration behavior.\n\n\n---\nname: testing-and-verification\ndescription:\n Use when adding or running tests, checking snapshots, choosing between Bun\n tests and Playwright, running lint/format/typecheck, or deciding the\n verification scope for a change.\n---\n\n# Testing and Verification\n\n## Baseline Commands\n\nAfter code changes, run the required baseline (moon tasks run from anywhere in\nthe repo, including CI-marked agent shells):\n\n```bash\nmoon run root:format root:lint\n```\n\nUseful check/fix pairs on the root project:\n\n```bash\nmoon run root:format-check\nmoon run root:format\nmoon run root:lint\nmoon run root:lint-fix\nmoon run root:lint-css\nmoon run root:lint-css-fix\n```\n\nFor code changes, also run the relevant typecheck (moon builds workspace\ndependencies first automatically):\n\n```bash\nmoonx :typecheck\n# or, scoped to what actually changed:\nmoonx :typecheck --affected\n```\n\nThe React Compiler lint rules (`react/*` in `.oxlintrc.json`) assume React.\n`packages/trees/src/render/**/*.tsx` and\n`packages/trees/src/components/**/*.tsx` are Preact, so an `overrides` entry\nthere turns `react/refs` off for those globs. Put new Preact components under\nthose directories instead of adding per-file `oxlint-disable` headers.\n\n## Unit and Integration Tests\n\nUse Bun's built-in test runner. Tests usually live in a `test/` folder inside\neach package and use `describe`, `test`, and `expect` from `bun:test`.\n\nPrefer unit or integration tests by default:\n\n```bash\nmoonx diffs:test\nmoonx trees:test\n```\n\n`moon run :test` runs every project's suite. Tests import workspace dependencies\nthrough their built dist, so moon builds those first; running `bun test`\ndirectly inside a package also works when dist is fresh.\n\n## Snapshots\n\nBun supports `toMatchSnapshot()`. Avoid new snapshot coverage unless it is\nshallow and narrowly scoped to the exact behavior under test.\n\nUpdate snapshots from the package directory:\n\n```bash\nbun test -u\n```\n\n## Browser and E2E Tests\n\nAdd Playwright/browser E2E tests only when behavior cannot be validated without\na real browser engine. Good candidates include computed style checks, shadow DOM\nboundaries, and browser-only rendering behavior.\n\nKeep E2E coverage small and high-value:\n\n```bash\nmoonx trees:coverage\nmoonx trees:test-e2e\nmoonx path-store:test-demo\nmoonx docs:test-e2e\n```\n\nIf E2E fixtures or dev servers are started in a worktree, follow the cleanup\ncontract from the `worktrees-and-dev-servers` skill.\n\n\n---\nname: tooling-and-dependencies\ndescription:\n Use when running repo scripts, adding or changing dependencies, editing\n package.json files, installing packages, publishing packages, or deciding when\n pnpm package operations versus Bun runtime commands should be invoked.\n---\n\n# Tooling and Dependencies\n\n## Toolchain (proto)\n\n- Tool versions (bun, pnpm, node, moon, gh) are pinned in `.prototools` and\n managed by [proto](https://moonrepo.dev/docs/proto); its shims put the pinned\n versions on PATH inside the repo. `proto use` installs everything after a pin\n changes.\n- Bump a tool by editing `.prototools` only — never install tools globally or\n pin versions elsewhere. moon's version is additionally enforced by\n `versionConstraint` in `.moon/workspace.yml` and mirrored as the\n `@moonrepo/cli` catalog entry (for Vercel builders without proto); keep all\n three in sync.\n- CI and local shells resolve the same toolchain: CI installs it with\n `moonrepo/setup-toolchain`, which runs `proto install` against the same\n `.prototools`.\n\n## Package Manager and Runtime\n\n- Use `pnpm` for package operations: install, add, remove, dedupe, lockfile,\n package-runner, and publish work.\n- Do not use `bun`, `npm`, `yarn`, `npx`, or other package runners for package\n operations unless there is a specific documented reason.\n- Bun remains the direct TypeScript runtime and Bun test runner where current\n moon tasks use it. Local scripts may still be `.ts` files without a separate\n compile step.\n\n## Dependency Catalog\n\nThis monorepo uses the `catalog` in `pnpm-workspace.yaml`.\n\n- Never add a version directly to an individual package's `package.json` by\n default.\n- To add a dependency:\n 1. Add the exact version to `pnpm-workspace.yaml` under `catalog`, for example\n `\"new-package\": \"1.2.3\"`.\n 2. Reference it from the package with `\"new-package\": \"catalog:\"`.\n- Do not run `pnpm add ` inside a package directory; it writes direct\n versions and breaks the catalog pattern unless you manually normalize them.\n- Published packages may intentionally use ranges for end-user compatibility.\n `apps/docs` should use catalog versions; published packages such as\n `packages/diffs` may use ranges only when that is intentional.\n\n## Tasks\n\n- All build/dev/test/lint entrypoints are moon tasks; package.json scripts exist\n only for npm lifecycle hooks (`prepublishOnly`). Never add task scripts back\n to a package.json.\n- Tasks are defined in `.moon/tasks/*.yml` (inherited) and each project's\n `moon.yml`. Repo-wide tooling (format, lint, icons, clean) lives on the `root`\n project.\n- Run tasks from anywhere in the repo:\n\n```bash\nmoon run :\nmoonx : # same engine; shorthand for moon exec\nmoonx : -- --flags # forward arguments after --\nmoon run :test # a task across every project that has it\nmoon tasks # discover a project's tasks\n```\n\n`moon run` and `moonx` (an alias binary for `moon exec`) execute the same action\npipeline: identical dependency resolution, caching, and affected support. Use\nthem interchangeably; docs write `moon run` for canonical commands and `moonx`\nin interactive examples. The one practical difference: `moonx`/`moon exec`\nexposes CI-behavior overrides (`--ignore-ci-checks`, `--ci `) that\n`moon run` lacks. `moon ci` is a third thing — the affected-aware orchestrator\nused only by `.github/workflows/ci.yml`; never reach for it locally.\n\nmoon builds dependency projects first (`deps: ['^:build']`), caches outputs, and\nskips tasks whose inputs have not changed. Local-only tasks set explicit options\ninstead of moon presets (presets force `runInCI: skip`, which moon refuses to\nrun in CI-detected shells; agent harnesses export `CI=1`):\n\n- No graph edges at all (formatters, benchmarks, wt, servers spawned by\n playwright): use `runInCI: 'always'` — runnable everywhere, and never in the\n CI pipeline because a task with no deps or dependents is never affected\n through the graph.\n- Connected to the build graph (dev/prod, e2e variants, publish guards): keep\n `runInCI: 'skip'` — `moon ci --include-relations` runs affected\n runInCI-enabled tasks even when unrequested, which would pull them into CI.\n Run them in CI-marked shells with `moonx --ignore-ci-checks` (works\n regardless of the shell's CI env). For non-moon commands that CI-gate\n themselves, unset the var instead: `CI= pnpm publish --dry-run`.\n\n\n---\nname: typescript-monorepo\ndescription:\n Use when adding or changing packages/apps, TypeScript configs, workspace\n dependencies, package references, exports, or monorepo project-reference\n relationships.\n---\n\n# TypeScript Monorepo\n\n## TypeScript\n\nUse TypeScript everywhere practical. Compiler settings are intentionally fairly\nstrict.\n\n- Shared compiler options live in `tsconfig.options.json`.\n- Root `tsconfig.json` manages project references across the monorepo.\n- Typechecking uses TypeScript 7's native `tsc` (the successor to the `tsgo`\n preview) and runs through moon: `moonx :typecheck` (moon builds\n workspace dependencies first, since types resolve through each dependency's\n built dist). Next runs the same `tsc` for its build-time check through\n `experimental.useTypeScriptCli`, which is on by default since Next 16.3.\n\n## Project References\n\nWhen adding a new package or app:\n\n- Add it to the root `tsconfig.json` references.\n- Ensure its local `tsconfig.json` follows existing package/app patterns.\n- Give it a `moon.yml` (language, layer, tags, and any project-specific tasks);\n shared tasks come from `.moon/tasks/*.yml` via tags or project language.\n\nWhen one workspace package depends on another:\n\n- Add the dependency as `workspace:*` in the consuming package.\n- Add the dependency to the consuming package's TypeScript `references` block\n when needed for accurate and fast typechecking.\n\n## Workspace Dependencies\n\nUse the `pnpm-workspace.yaml` catalog rules from `tooling-and-dependencies` for\nexternal packages. Use `workspace:*` for internal package dependencies.\n\nIf a package is published, review its `exports`, `typesVersions`, `files`, peer\ndependencies, and its moon `prepublish` task chain before changing public\nentrypoints or dependency ranges.\n\n\n---\nname: worktrees-and-dev-servers\ndescription:\n Use when working with the repo's moonx root:wt worktree helper, Pierre-managed\n worktrees, dev-server port offsets, stale server cleanup, Playwright fixtures,\n or Chrome debug instances. Do not use this as a substitute for host-provided\n workspace isolation.\n---\n\n# Worktrees and Dev Servers\n\nPierre includes a repo-specific `git worktree` helper for local/manual\nparallelization outside host-managed agent workspaces. Managed Pierre worktrees\nlive at:\n\n```text\n~/pierre/pierre-worktrees//\n```\n\nEach managed Pierre worktree owns a port offset so dev servers, E2E fixtures,\nand the Chrome remote-debug instance do not collide. The main clone keeps\nhistorical default ports; linked Pierre worktrees shift ports.\n\nIf you are already inside a Conductor, Codex, Claude, or other host-provided\nworkspace, do not create another worktree unless the user explicitly asks for a\nPierre-managed worktree. Still use this skill when you start repo dev servers or\nE2E fixtures, because the cleanup and port-offset rules apply to those scripts.\n\n## Worktree Commands\n\nThe `wt` suite is defined in `scripts/wt.ts`, exposed as the `root:wt` moon\ntask, and manages only Pierre-managed worktrees:\n\n```bash\nmoonx root:wt -- new # create a worktree, allocate offset, pnpm install\nmoonx root:wt -- rm # kill its processes, remove the worktree\nmoonx root:wt -- clean # kill zombie servers on all managed worktree ports\nmoonx root:wt -- clean # clean one managed worktree\nmoonx root:wt -- ps # show per-worktree port status (LISTEN / -)\nmoonx root:wt -- list # summary of managed + external worktrees\n```\n\nPort-binding moon tasks read the offset from `/.env.worktree` via\ntheir `envFile` option. Before starting, dev tasks run `scripts/run-dev.sh` to\nkill any stale process bound to the target port.\n\n## Cleanup Contract\n\nIf you start dev servers, Playwright fixtures, or Chrome debug instances inside\na worktree, run cleanup before completing your turn:\n\n```bash\nmoonx root:wt -- clean \n```\n\nUse `moonx root:wt -- clean` when you do not know the slug or need to clean\nevery managed worktree. Use `moonx root:wt -- rm ` only when intentionally\ntearing down the worktree itself.\n\n\n# Core API\n\nThis reference covers components, parsing, merge conflicts, and file extension\nAPIs from `@pierre/diffs`.\n\n## Contents\n\n- [File components](#file-components)\n- [Virtualized components](#virtualized-components)\n- [`File` members](#file-members)\n- [`FileDiff` members](#filediff-members)\n- [`CodeView` members](#codeview-members)\n- [Parsing and patch APIs](#parsing-and-patch-apis)\n- [Merge conflict APIs](#merge-conflict-apis)\n- [Annotation APIs](#annotation-apis)\n- [File extension APIs](#file-extension-apis)\n\n## File components\n\n| Export | Kind | Purpose |\n| --------------------------------------- | -------- | ------------------------------------------------------------- |\n| `File` | Class | Renders one syntax-highlighted file. |\n| `FileOptions` | Type | Configures file display, interaction, slots, and callbacks. |\n| `FileRenderProps` | Type | Defines file input and a render target. |\n| `FileHydrateProps` | Type | Defines file input and preloaded markup for hydration. |\n| `FileDiff` | Class | Renders a file diff from files or parsed metadata. |\n| `FileDiffOptions` | Type | Configures diff display, interaction, slots, and callbacks. |\n| `FileDiffRenderBaseProps` | Type | Defines shared diff render input. |\n| `FileDiffRenderProps` | Type | Adds files or parsed metadata to diff render input. |\n| `FileDiffHydrationProps` | Type | Defines diff input and preloaded markup for hydration. |\n| `FileDiffType` | Type | Identifies a standard or unresolved diff instance. |\n| `UnresolvedFile` | Class | Renders one file with merge conflict controls. |\n| `UnresolvedFileOptions` | Type | Configures merge conflict display and callbacks. |\n| `UnresolvedFileRenderProps` | Type | Defines merge conflict render input. |\n| `UnresolvedFileHydrationProps` | Type | Defines merge conflict input for hydration. |\n| `MergeConflictActionsTypeOption` | Type | Selects no actions, default actions, or a custom renderer. |\n| `RenderMergeConflictActions` | Type | Defines a vanilla conflict action renderer. |\n| `getUnresolvedDiffHunksRendererOptions` | Function | Converts unresolved-file options to hunk renderer options. |\n| `CodeView` | Class | Renders a virtualized list of files and diffs. |\n| `CodeViewOptions` | Type | Configures list layout, items, slots, selection, and editing. |\n| `CodeViewLineSelection` | Type | Associates a selected range with one item ID. |\n| `CodeViewRenderedFileItem` | Type | Describes one mounted file item. |\n| `CodeViewRenderedDiffItem` | Type | Describes one mounted diff item. |\n| `CodeViewRenderedItem` | Type | Represents a mounted file or diff item. |\n| `CodeViewCoordinator` | Type | Coordinates React slots with the vanilla list. |\n| `CodeViewSlotSnapshot` | Type | Describes mounted items and list header or footer hosts. |\n| `CodeViewScrollListener` | Type | Receives list scroll changes. |\n| `CODE_VIEW_FILE_OPTION_KEYS` | Value | Lists file options that `CodeView` passes to an item. |\n| `CODE_VIEW_DIFF_OPTION_KEYS` | Value | Lists diff options that `CodeView` passes to an item. |\n\n## Virtualized components\n\n| Export | Kind | Purpose |\n| -------------------------------------------------- | ----- | ----------------------------------------------------------- |\n| `Virtualizer` | Class | Tracks a simple viewport and connected render instances. |\n| `VirtualizerConfig` | Type | Configures overscroll, observation margin, and resize logs. |\n| `VirtualizedFile` | Class | Adds simple viewport behavior to `File`. |\n| `VirtualizedFileDiff` | Class | Adds simple viewport behavior to `FileDiff`. |\n| `VIRTUALIZED_FILE_DIFF_LAYOUT_CHECKPOINT_INTERVAL` | Value | Sets the line interval for virtual diff layout checkpoints. |\n\n## `File` members\n\n| Member | Purpose |\n| --------------------------------------------- | ---------------------------------------------------- |\n| `new File(options?, workerManager?)` | Creates one file renderer. |\n| `render(props)` | Renders file contents. |\n| `hydrate(props)` | Attaches to preloaded file markup. |\n| `rerender()` | Renders the current file again. |\n| `setOptions(options)` | Replaces file options. |\n| `setThemeType(themeType)` | Selects system, light, or dark theme mode. |\n| `onThemeChange()` | Applies a changed theme. |\n| `setLineAnnotations(annotations)` | Replaces file annotations. |\n| `setSelectedLines(range, options?)` | Replaces the selected line range. |\n| `setEditorActiveLine(line, options?)` | Marks the editor's active line. |\n| `getHoveredLine()` | Gets the current hovered line. |\n| `getOrCreateLineCache(file?)` | Gets cached source lines. |\n| `attachEditor(editor)` | Attaches an editor and returns a detach function. |\n| `applyDocumentChange(document, annotations?)` | Applies an editor document update. |\n| `updateRenderCache(tokens, themeType)` | Updates highlighted token cache entries. |\n| `primeHighlightCache()` | Preloads the highlighted file result. |\n| `renderPlaceholder(height)` | Renders a fixed-height placeholder. |\n| `virtualizedSetup()` | Prepares the instance for a virtualizer. |\n| `flushManagers()` | Applies deferred interaction and size manager state. |\n| `cleanUp(recycle?)` | Releases rendered resources. |\n\n## `FileDiff` members\n\n`FileDiff` supports the shared `File` update, selection, annotation, editor,\nhydration, placeholder, and cleanup members with diff data.\n\n| Member | Purpose |\n| -------------------------------------------- | ------------------------------------------------ |\n| `new FileDiff(options?, workerManager?)` | Creates one diff renderer. |\n| `render(props)` | Parses or renders diff input. |\n| `hydrate(props)` | Attaches to preloaded diff markup. |\n| `rerender()` | Renders the current diff again. |\n| `setOptions(options)` | Replaces diff options. |\n| `getLineIndex(line, side?)` | Maps a displayed line to row and column indexes. |\n| `handleExpandHunk(index, direction, count?)` | Handles a hunk expansion request. |\n| `expandHunk(index, direction, count?)` | Expands hidden context around one hunk. |\n| `completeEditSession()` | Recomputes diff metadata after an edit session. |\n| `isLineRenderable(line)` | Tests whether an additions line is visible. |\n| `getNearestRenderableLine(line, direction)` | Finds a visible additions line. |\n| `revealLine(line)` | Expands context to show an additions line. |\n| `primeHighlightCache(diff?)` | Preloads the highlighted diff result. |\n\n## `CodeView` members\n\n| Member | Purpose |\n| ---------------------------------------- | -------------------------------------------- |\n| `new CodeView(options?, workerManager?)` | Creates one virtualized list. |\n| `setup(root)` | Attaches the list to its scroll root. |\n| `setItems(items)` | Replaces all items. |\n| `addItem(item)` | Appends one item. |\n| `addItems(items)` | Appends several items. |\n| `getItem(id)` | Gets one item by ID. |\n| `updateItem(item)` | Replaces one item by ID. |\n| `updateItemId(oldId, newId)` | Changes one item ID. |\n| `getEditor(id)` | Gets the active editor for an item. |\n| `scrollTo(target)` | Scrolls to a position, item, line, or range. |\n| `setSelectedLines(selection, options?)` | Sets the selected item and range. |\n| `getSelectedLines()` | Gets the selected item and range. |\n| `clearSelectedLines(options?)` | Clears the selected lines. |\n| `setOptions(options)` | Replaces list options. |\n| `onThemeChange()` | Applies a changed theme to list items. |\n| `render(immediate?)` | Schedules or performs a render. |\n| `getWindowSpecs()` | Gets the current virtual window. |\n| `getContainerElement()` | Gets the scroll content element. |\n| `getHeaderElement()` | Gets the list header host. |\n| `getFooterElement()` | Gets the list footer host. |\n| `getRenderedItems()` | Gets mounted items. |\n| `setSlotCoordinator(coordinator?)` | Sets the external slot coordinator. |\n| `getSlotSnapshot(coordinator)` | Gets the coordinator's mounted slot state. |\n| `subscribeToScroll(listener)` | Subscribes to scroll changes. |\n| `getLocalTopForInstance(instance)` | Gets an instance offset inside the list. |\n| `getTopForItem(id)` | Gets an item offset inside the list. |\n| `instanceChanged(instance, layoutDirty)` | Reports a render instance change. |\n| `reset()` | Clears items and render state. |\n| `cleanUp()` | Releases list resources. |\n\n## Parsing and patch APIs\n\n| Export | Purpose |\n| ---------------------------- | ----------------------------------------------------- |\n| `parseDiffFromFile` | Creates `FileDiffMetadata` from old and new files. |\n| `parsePatchFiles` | Parses a patch string into file diff metadata. |\n| `processPatch` | Parses one patch section. |\n| `processFile` | Converts one parsed patch file to `FileDiffMetadata`. |\n| `getSingularPatch` | Selects one file patch from a patch string. |\n| `trimPatchContext` | Limits unchanged context in patch text. |\n| `hydratePartialDiff` | Adds loaded file contents to partial diff metadata. |\n| `cloneFileDiffMetadata` | Creates a structural copy of diff metadata. |\n| `cleanLastNewline` | Normalizes the final newline for diff input. |\n| `getLineEndingType` | Detects a file's line-ending sequence. |\n| `getTotalLineCountFromHunks` | Counts rendered rows across hunks. |\n| `parseLineType` | Parses one patch line marker and content. |\n| `ParsedLine` | Describes the result from `parseLineType`. |\n\n## Merge conflict APIs\n\n| Export | Purpose |\n| ---------------------- | --------------------------------------------------------------- |\n| `resolveConflict` | Applies one current, incoming, or combined conflict resolution. |\n| `resolveRegion` | Resolves one parsed merge conflict region. |\n| `diffAcceptRejectHunk` | Applies accept or reject behavior to one change hunk. |\n\n## Annotation APIs\n\n| Export | Purpose |\n| ---------------------------- | ---------------------------------------------------------- |\n| `isFileAnnotation` | Tests whether one annotation targets a file line. |\n| `isDiffAnnotation` | Tests whether one annotation targets a diff side and line. |\n| `isFileAnnotationCollection` | Tests whether an array contains file annotations. |\n| `isDiffAnnotationCollection` | Tests whether an array contains diff annotations. |\n\n## File extension APIs\n\n| Export | Purpose |\n| ---------------------------- | ------------------------------------------------ |\n| `getFiletypeFromFileName` | Infers a language from a file name. |\n| `setCustomExtension` | Maps one file name or extension to a language. |\n| `replaceCustomExtensions` | Replaces all custom mappings. |\n| `getCustomExtensionsMap` | Gets a copy of custom mappings. |\n| `getCustomExtensionsVersion` | Gets the mapping revision. |\n| `EXTENSION_TO_FILE_FORMAT` | Maps built-in extensions and names to languages. |\n| `setLanguageOverride` | Assigns a language to parsed diff files. |\n\n\n# Editor API\n\nThis reference lists the primary exports from `@pierre/diffs/edit` and the\neditor APIs used by common integrations.\n\n## Exports\n\n| Export | Kind | Purpose |\n| --------------------------- | ----- | -------------------------------------------------------------- |\n| `CaretMetadata` | Type | Supplies the color shared by a remote caret and its highlight. |\n| `Editor` | Class | Adds text editing to a `File` or `FileDiff` instance. |\n| `EditorCaret` | Type | Describes an externally owned caret or highlighted selection. |\n| `EditStateManager` | Value | Manages keyed in-memory edit history and state. |\n| `ClearEditStateOptions` | Type | Selects retained state parts to clear. |\n| `EditState` | Type | Holds one complete live editing session. |\n| `EditorInitialState` | Type | Selects state fields to supply on first attachment. |\n| `EditorChange` | Type | Describes one normalized editor change. |\n| `EditorChangeEvent` | Type | Provides normalized edits and the current document. |\n| `EditorActiveLineOptions` | Type | Configures reveal behavior for an editor active line. |\n| `EditorEditCompleteEvent` | Type | Unites file and diff completion events for editor observation. |\n| `FileEditCompleteEvent` | Type | Describes a completed file edit session. |\n| `FileDiffEditCompleteEvent` | Type | Describes a completed diff edit session. |\n| `EditorCommand` | Type | Names an editor command. |\n| `EditorType` | Type | Selects a `file` or `file-diff` editor surface. |\n| `EditorFactory` | Type | Defines an editor-type-aware editor factory. |\n| `EditorFocusOptions` | Type | Selects a focus target and scroll behavior. |\n| `EditorKeymap` | Type | Defines ordered custom shortcut groups. |\n| `EditorOptions` | Type | Configures history, initial state, behavior, and events. |\n| `EditorShortcut` | Type | Defines one command shortcut. |\n| `EditorSelection` | Type | Adds caret direction to an editor range. |\n| `EditorViewState` | Type | Holds selections and editor-owned viewport offsets. |\n| `EditorViewportState` | Type | Holds horizontal and optional vertical scroll offsets. |\n| `KeyboardKey` | Type | Names a key accepted by an editor shortcut. |\n| `KeyboardModifier` | Type | Names a modifier accepted by an editor shortcut. |\n| `TextDocument` | Class | Stores text, positions, edits, search, and undo history. |\n| `TextDocumentChange` | Type | Describes the lines and characters changed by an edit. |\n| `Position` | Type | Identifies a zero-based line and character. |\n| `Range` | Type | Identifies a start and end position. |\n| `ResolvedTextEdit` | Type | Stores an edit with resolved document offsets. |\n| `SelectionDirection` | Type | Selects backward, neutral, or forward selection direction. |\n| `TextEdit` | Type | Replaces one range with new text. |\n| `Marker` | Type | Describes an editor diagnostic marker. |\n| `MarkerSeverity` | Type | Selects an editor marker severity. |\n\n## Lower-level exports\n\nThe edit entrypoint also exposes the state-management, keyboard-resolution,\nmarker-rendering, and popover-placement building blocks used by `Editor`.\n\n| Export | Kind | Purpose |\n| --------------------------------------- | -------- | --------------------------------------------------------------------- |\n| `ManagedEditSession` | Type | Selects mutable in-progress editor state by editor type. |\n| `ManagedFileEditSession` | Type | Holds mutable state for an active file editor session. |\n| `ManagedFileDiffEditSession` | Type | Holds mutable state for an active file-diff editor session. |\n| `cloneEditorViewState` | Function | Clones editor selections and viewport state. |\n| `toManagedEditState` | Function | Returns complete edit state when a managed session has required data. |\n| `resolveEditorCommandFromKeyboardEvent` | Function | Resolves a keyboard event through custom and default editor keymaps. |\n| `resolveFindAgainShortcut` | Function | Recognizes the next or previous native find shortcut. |\n| `MarkerRenderOptions` | Type | Supplies marker rendering, measurement, and popover dependencies. |\n| `MarkerRenderer` | Class | Renders marker ranges and marker hover popovers. |\n| `markerSeverityDatasetKey` | Function | Maps a marker severity to its DOM dataset key. |\n| `POPOVER_BOUNDARY_LINES` | Value | Sets the document-edge fallback threshold for popover placement. |\n| `POPOVER_FLIP_HYSTERESIS_PX` | Value | Sets the clearance required before a flipped popover returns. |\n| `PopoverPlacementBounds` | Type | Describes vertical popover placement bounds. |\n| `PopoverViewportBounds` | Type | Describes all visible viewport edges for popover clamping. |\n| `PopoverManagerOptions` | Type | Supplies active-popover state callbacks to `PopoverManager`. |\n| `PopoverManager` | Class | Tracks viewport geometry and stable popover placement. |\n| `setPopoverPositionStyles` | Function | Writes the CSS properties used to position and clamp a popover. |\n\n## `EditorOptions` fields\n\n| Field | Purpose |\n| ------------------------ | -------------------------------------------------------- |\n| `historyMaxEntries` | Limits the undo stack. |\n| `ownsVerticalViewport` | Opts into vertical scroll retention at construction. |\n| `initialState` | Supplies partial or complete state on first attach. |\n| `keymap` | Adds shortcut groups checked before the defaults. |\n| `roundedSelection` | Controls rounded selection corners. |\n| `matchBrackets` | Controls matching-bracket highlights. |\n| `autoSurround` | Controls quote and bracket insertion around a selection. |\n| `languageCommentConfig` | Overrides comment tokens by language. |\n| `enabledSelectionAction` | Enables the selection action surface. |\n| `clipboard` | Supplies a text clipboard reader. |\n| `renderSelectionAction` | Produces the selection action element. |\n| `renderCaret` | Produces an externally owned caret element. |\n| `onAttach` | Receives the editor and attached surface. |\n| `onChange` | Receives the event, including its editor instance. |\n| `onComplete` | Observes the completed file or diff event. |\n| `onFocus` | Runs after the editor gains focus. |\n| `onBlur` | Runs after the editor loses focus. |\n\nFor a `file-diff` editor, view-only `initialState` can omit document and diff\nmetadata. Transferring an edited document and its undo/redo history requires the\nmatching `document`, `fileInfo`, and `diffSession` from one complete\n`EditState`.\n\n`onComplete` receives the exact frozen event that is also passed to the\ncomponent's `onEditComplete` or CodeView's `onItemEditComplete`. The editor\nobserver runs first and still runs when the component callback is missing. You\ncannot accept or reject from this API. It is here for symmetry, but most\nintegrations should use those component callbacks instead.\n\nUse `editStateKey` for ordinary same-runtime restoration. It retains the draft,\nundo/redo history, selections, horizontal code scroll, eligible vertical scroll,\nand FileDiff resume metadata without an application synchronization loop. It is\nbounded in-memory state and does not survive a reload.\n\nUse `getViewState()` and `setViewState()` for an isolated selection/view copy or\ndurable application persistence. An attached surface reports horizontal\n`scrollLeft`. It reports `scrollTop` only when `ownsVerticalViewport: true` was\npassed to the constructor and the surface exclusively owns an element viewport.\nVirtualization alone does not imply ownership; page, ancestor, and CodeView\nshared scrolling remain application/viewer state.\n\n`getEditState()` exposes the raw objects from the latest complete edit-lifecycle\ncheckpoint. Checkpoints run after synchronization, document edits, explicit\n`setViewState()` calls, recycling, and completion. Selection or scroll movement\nalone does not update it; use `getViewState()` for an exact live copy. State\nremains available while rendering is recycled and during `onComplete`, and\nreturns `undefined` before synchronization or after completion. The result is\nborrowed editor-owned state rather than a serialization format.\n\n## `Editor` members\n\n| Member | Purpose |\n| -------------------------------------------------------- | ------------------------------------------------------- |\n| `new Editor(type, options?, editStateKey?)` | Creates an editor with optional keyed state retention. |\n| `type` | Identifies the editor as `file` or `file-diff`. |\n| `edit(instance)` | Attaches and returns the normal completion disposer. |\n| `setOptions(options)` | Merges editor options. |\n| `applyEdits(edits, updateHistory?)` | Applies programmatic text edits. |\n| `canUndo` | Reports whether undo has an entry. |\n| `canRedo` | Reports whether redo has an entry. |\n| `undo()` | Reverts the latest edit. |\n| `redo()` | Reapplies the latest reverted edit. |\n| `getFile()` | Gets the current file contents. |\n| `getText()` | Gets the current text. |\n| `getViewState()` | Gets selections and editor-owned view state. |\n| `setViewState(state)` | Sets selections and editor-owned view state. |\n| `getEditState()` | Gets the latest edit-lifecycle state checkpoint. |\n| `setSelections(selections)` | Sets directed selection ranges. |\n| `setCarets(carets)` | Replaces the externally owned caret and highlight list. |\n| `setMarkers(markers)` | Sets diagnostic markers. |\n| `focus(options?)` | Focuses the editor. |\n| `blur()` | Removes editor focus. |\n| `cleanUp(reason?: 'discard' \\| 'recycle' \\| 'complete')` | Suspends rendering or completes the editing session. |\n\n`editStateKey` opts an editor into retained in-memory sessions across editor\ninstances. File and file-diff namespaces are independent and each keeps up to\n100 inactive entries by default. The same type/key cannot be active in two\neditors at once.\n\nCall the disposer returned by `edit(instance)` for the normal session-ending\npath; it is equivalent to `cleanUp('complete')` and installs an accepted\ncompletion result. `cleanUp('discard')` still publishes the completion event but\ndoes not install its result. `cleanUp('recycle')` suspends rendering without\nending the session or changing the editor-component association. Calling\n`edit(instance)` again resumes rendering for that same component.\n\n## `EditStateManager` members\n\n| Member | Purpose |\n| ----------------------------------- | --------------------------------------------------------------- |\n| `get(type, editStateKey)` | Borrows active or inactive complete state without touching LRU. |\n| `clear(type, editStateKey, parts?)` | Clears inactive complete or granular state. |\n| `clearAll()` | Clears all inactive state without mutating active editors. |\n| `setCapacity(capacity)` | Sets each namespace's inactive retained-state capacity. |\n\n`clear()` returns `false` for active or missing state. Omit `parts` to remove\nthe complete entry. `{ document: true }` also removes the complete entry because\nall other parts depend on it. Use `{ history: true }`, `{ selections: true }`,\n`{ view: true }`, or `{ editor: true }` to keep the document while clearing undo\nhistory, cursor state, scroll state, or both view-state parts respectively.\n\nFor durable persistence, store `FileContents` and optional JSON-safe\n`EditorViewState` separately, then construct a fresh `TextDocument` when\nrestoring. Complete `EditState` and undo/redo history are not serialization\ncontracts.\n\n## `TextDocument` members\n\n| Member | Purpose |\n| ---------------------------------------------------- | ----------------------------------------------------- |\n| `new TextDocument(uri, text, languageId?, version?)` | Creates a text document. |\n| `uri` | Gets the document identifier. |\n| `languageId` | Gets the language identifier. |\n| `version` | Gets the document version. |\n| `lineCount` | Gets the line count. |\n| `eol` | Gets the line-ending sequence. |\n| `canUndo` | Reports whether undo has an entry. |\n| `canRedo` | Reports whether redo has an entry. |\n| `positionAt(offset)` | Converts an offset to a position. |\n| `positionsAt(offsets)` | Converts several offsets to positions. |\n| `offsetAt(position)` | Converts a position to an offset. |\n| `getText(range?)` | Gets all text or one range. |\n| `getLineText(line, includeLineBreak?)` | Gets one line. |\n| `normalizeEol(text)` | Converts text to the document line ending. |\n| `getLineLength(line, includeLineBreak?)` | Gets one line length. |\n| `charAt(offsetOrPosition)` | Gets one character. |\n| `getTextSlice(start, end)` | Gets text between two offsets. |\n| `findNextNonOverlappingSubstring(needle, occupied)` | Finds an unused substring range. |\n| `search(params)` | Finds text ranges. |\n| `applyEdits(edits, ...)` | Resolves and applies position-based edits. |\n| `resolveEdits(edits)` | Converts position-based edits to offset edits. |\n| `applyResolvedEdits(edits, ...)` | Applies offset-based edits. |\n| `setLastUndoSelectionsAfter(selections)` | Associates selections with the latest history entry. |\n| `setLastUndoLineAnnotations(before, after)` | Associates annotations with the latest history entry. |\n| `undo()` | Reverts one document history entry. |\n| `redo()` | Reapplies one document history entry. |\n| `normalizePosition(position)` | Clamps a position to the document. |\n\n\n# Highlighting API\n\n`preferredHighlighter` selects `'shiki-js'` (default), `'shiki-wasm'`, or\n`'highlights'`. Backends load lazily. File, FileDiff, Editor, FileStream, SSR\npreload options, and worker highlighter options accept this selection.\n\nOnly one backend type can be loaded per JavaScript realm (page, worker, or SSR\nprocess). Requests without `preferredHighlighter` use the loaded type, else\n`'shiki-js'`. Shared-highlighter requests (components, `getSharedHighlighter`,\n`preloadHighlighter`) keep using the loaded type even when they name another\none; they do not throw. `createHighlighter` with another type throws. To switch\ntypes, dispose every instance of the loaded type, shared or from\n`createHighlighter`. `getHighlighterType()` returns the loaded type.\n\n## Shared highlighter\n\n```ts\nimport { getSharedHighlighter } from '@pierre/diffs';\n\nconst highlighter = await getSharedHighlighter({\n preferredHighlighter: 'highlights',\n themes: ['pierre-dark'],\n langs: ['typescript'],\n});\nconst html = highlighter.codeToHtml('const value = 1;', {\n lang: 'typescript',\n theme: 'pierre-dark',\n});\n```\n\n`DiffsHighlighter` is an abstract class with `name`, `themeResolver`,\n`getTheme`, `codeToHtml`, `codeToTokens`, `createEditorTokenizer`,\n`createStreamTokenizer`, `loadLanguages`, `hasLoadedLanguages`,\n`attachLanguages`, and `dispose`. Highlights bundles its lexers, so its language\nmethods do nothing and `hasLoadedLanguages` is true until disposal. Import\nbackend-specific Shiki APIs and types from `shiki` directly.\n\n| Export | Purpose |\n| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |\n| `getSharedHighlighter` | Gets or creates the shared instance and loads themes/languages. |\n| `createHighlighter` | Creates an independently disposable instance: `createHighlighter('highlights')`. |\n| `getHighlighterType` | Returns the backend type loaded in this realm, if any. |\n| `preloadHighlighter` | Loads the same settings before a render. |\n| `getHighlighterIfLoaded` | Gets the loaded shared instance when its requested settings are available. |\n| `isHighlighterLoaded`, `isHighlighterLoading`, `isHighlighterNull` | Inspect shared state without arguments. Use `getHighlighterIfLoaded()` to obtain a ready instance. |\n| `disposeHighlighter` | Disposes the shared instance and clears resolved caches; retained `createHighlighter` instances keep their themes. |\n| `getHighlighterOptions` | Converts component options to highlighter input. |\n| `getHighlighterThemeStyles` | Creates component CSS from a loaded theme. |\n| `getThemes` | Converts a theme name or light/dark pair to a name list. |\n\n## Themes\n\n`DiffsTheme` contains `name`, `type`, `fg`, `bg`, optional editor `colors`, and\nbackend syntax data: `textmate` for Shiki and `zed` for Highlights. Bundled\nPierre and Shiki theme names also resolve to bundled Highlights palettes.\n\n| Export | Purpose |\n| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |\n| `registerCustomTheme(name, loader, type = 'textmate')` | Registers a loader with type `'textmate'` for Shiki, `'zed'` for Highlights, or `'diffs'` for portable themes. |\n| `createCSSVariablesTheme` | Creates a portable palette; accepts name, variablePrefix (default `--diffs-`), variableDefaults, and fontStyle. |\n| `registerCustomCSSVariableTheme` | Preserves `(name, variableDefaults, fontStyle = false)` and the `--diffs-` prefix. |\n| `resolveTheme`, `resolveThemes` | Resolve themes; optional second argument selects the backend. |\n| `getResolvedOrResolveTheme`, `getResolvedThemes`, `hasResolvedThemes` | Read or populate the selected backend's cache. |\n| `attachResolvedThemes` | Seeds resolved themes into a highlighter, including worker instances. |\n| `areThemesAttached` | Checks cached themes; optionally takes a backend name or highlighter. |\n| `cleanUpResolvedThemes` | Clears caches, preserving registrations. |\n\n`createCSSVariablesTheme` previously re-exported Shiki's\n`createCssVariablesTheme`, whose default prefix is `--shiki-` and whose result\nis a raw Shiki registration. Pass `variablePrefix: '--shiki-'` to keep\nstylesheets written for that default, or import Shiki's helper directly when a\nraw registration is needed.\n\nLoaders return a theme directly or as a module's `default` export. Register one\nloader per name and type; explicit TextMate or Zed loaders take priority over a\nshared Diffs loader. TextMate and Diffs names must match the registration. Zed\nthemes use the registered name instead of their display name; a `ThemeFamily`\nuses its first member unless the loader selects another.\n\nResolve themes on the main thread before passing them to workers. For one theme\nacross backends, use `createCSSVariablesTheme` or a `DiffsTheme` containing both\n`textmate` (Shiki's normalized `ThemeRegistrationResolved`) and `zed` palettes.\n\n## Languages\n\n`registerCustomLanguage(name, loader, extensions?)` registers TextMate grammars\nfor Shiki. Highlights includes its supported lexers and ignores custom grammar\nregistrations. Explicit unknown languages fall back to plain text in Highlights.\n\n`resolveLanguage(s)`, `getResolvedLanguages`, `hasResolvedLanguages`,\n`getResolvedOrResolveLanguage`, `attachResolvedLanguages`,\n`areLanguagesAttached`, and `cleanUpResolvedLanguages` support Shiki grammar\nloading. Language loader/cache maps remain available for compatibility.\n\n## Rendering and streams\n\n`renderFileWithHighlighter` and `renderDiffWithHighlighter` create component\nsyntax trees from backend-independent tokens.\n\nUse `highlighter.createStreamTokenizer(options)` for incremental append-only\ninput and `highlighter.createEditorTokenizer(options)` for document editing.\n`FileStream` connects a readable code stream through `setup(source, wrapper)`,\naccepts `preferredHighlighter`, supports `setThemeType`, and releases its stream\nthrough `cleanUp()`.\n\n\n# React API\n\nThis reference lists the React-specific exports from `@pierre/diffs/react`. The\nentry also re-exports every type in [Shared types](api-types.md).\n\n## Components and hooks\n\n| Export | Kind | Purpose |\n| --------------------------- | --------- | --------------------------------------------------------- |\n| `File` | Component | Renders one code file. |\n| `FileDiff` | Component | Renders pre-parsed diff metadata. |\n| `MultiFileDiff` | Component | Parses and renders an old and new file pair. |\n| `PatchDiff` | Component | Parses and renders one unified patch string. |\n| `UnresolvedFile` | Component | Renders and resolves merge conflicts in one file. |\n| `CodeView` | Component | Renders a virtualized list of files and diffs. |\n| `Virtualizer` | Component | Provides simple viewport virtualization. |\n| `useVirtualizer` | Hook | Gets the nearest simple `Virtualizer` instance. |\n| `EditProvider` | Component | Supplies an editor factory. |\n| `useCreateEditor` | Hook | Gets the nearest editor factory. |\n| `WorkerPoolContextProvider` | Component | Creates and supplies a worker pool. |\n| `useWorkerPool` | Hook | Gets the nearest worker pool. |\n| `useFileInstance` | Hook | Creates and manages a vanilla `File` instance. |\n| `useFileDiffInstance` | Hook | Creates and manages a vanilla `FileDiff` instance. |\n| `useStableCallback` | Hook | Returns a stable callback that reads the latest function. |\n\n## Component and provider types\n\n| Export | Purpose |\n| ----------------------------------- | ----------------------------------------------------------------- |\n| `FileProps` | Defines props for `File`. |\n| `FileOptions` | Defines vanilla file options and the React `options` prop. |\n| `FileDiffProps` | Defines props for `FileDiff`. |\n| `MultiFileDiffProps` | Defines props for `MultiFileDiff`. |\n| `PatchDiffProps` | Defines props for `PatchDiff`. |\n| `UnresolvedFileProps` | Defines props for `UnresolvedFile`. |\n| `UnresolvedFileReactOptions` | Defines merge-conflict options for React. |\n| `DiffBasePropsReact` | Defines props shared by React diff components. |\n| `CodeViewProps` | Defines controlled or uncontrolled `CodeView` props. |\n| `ControlledCodeViewProps` | Defines `CodeView` props with `items`. |\n| `UncontrolledCodeViewProps` | Defines `CodeView` props with `initialItems`. |\n| `CodeViewReactOptions` | Defines the React-safe `CodeView` option set. |\n| `CodeViewHandle` | Defines imperative list, selection, scroll, and editor controls. |\n| `EditorFactory` | Re-exports the editor factory type from `@pierre/diffs/edit`. |\n| `EditProviderProps` | Defines the type-aware `EditProvider` factory prop. |\n| `MergeConflictActionsTypeOption` | Selects no actions, default actions, or a custom action renderer. |\n| `RenderMergeConflictActionContext` | Supplies conflict resolution to a custom action renderer. |\n| `RenderMergeConflictActions` | Defines a custom conflict action renderer. |\n| `WorkerInitializationRenderOptions` | Defines initial worker languages and render options. |\n| `WorkerPoolOptions` | Defines the worker factory, pool size, and cache size. |\n\n## Contexts and render helpers\n\n| Export | Kind | Purpose |\n| ------------------------- | -------- | ------------------------------------------------------ |\n| `EditContext` | Context | Holds the editor factory. |\n| `WorkerPoolContext` | Context | Holds the worker pool. |\n| `VirtualizerContext` | Context | Holds the simple virtualizer. |\n| `GutterUtilitySlotStyles` | Value | Supplies style keys for gutter utility slots. |\n| `MergeConflictSlotStyles` | Value | Supplies style keys for merge conflict slots. |\n| `noopRender` | Function | Returns no React output for an optional render slot. |\n| `renderDiffChildren` | Function | Builds React portals for diff slots. |\n| `renderFileChildren` | Function | Builds React portals for file slots. |\n| `templateRender` | Function | Renders React content through a managed template slot. |\n\n\n# Low-level rendering API\n\nThis reference lists the renderer, manager, DOM helper, comparison, and constant\nexports from `@pierre/diffs`.\n\n## Contents\n\n- [Renderers](#renderers)\n- [Interaction manager](#interaction-manager)\n- [Size, scroll, and render managers](#size-scroll-and-render-managers)\n- [Comparison helpers](#comparison-helpers)\n- [Syntax tree and DOM helpers](#syntax-tree-and-dom-helpers)\n- [Layout and CSS helpers](#layout-and-css-helpers)\n- [Constants](#constants)\n\n## Renderers\n\n| Export | Kind | Purpose |\n| -------------------------------------- | ----- | ------------------------------------------------------- |\n| `FileRenderer` | Class | Converts one file to highlighted HAST, CSS, and HTML. |\n| `FileRendererOptions` | Type | Adds header mode to base code options. |\n| `FileRenderResult` | Type | Holds file HAST, CSS, row counts, and buffers. |\n| `DiffHunksRenderer` | Class | Converts diff hunks to highlighted column HAST and CSS. |\n| `DiffHunksRendererOptions` | Type | Configures one hunk renderer. |\n| `DiffHunksRendererOptionsWithDefaults` | Type | Describes resolved hunk renderer options. |\n| `HunksRenderResult` | Type | Holds rendered diff columns, metadata, and row count. |\n| `RenderedLineContext` | Type | Supplies line state to a line decoration. |\n| `LineDecoration` | Type | Defines a custom line wrapper and injected rows. |\n| `InjectedRow` | Type | Defines one row inserted around a unified line. |\n| `SplitInjectedRow` | Type | Defines one row inserted around a split line. |\n| `UnifiedInjectedRowPlacement` | Type | Selects placement before or after a unified row. |\n| `SplitInjectedRowPlacement` | Type | Selects side and placement for a split row. |\n| `UnifiedLineDecorationProps` | Type | Supplies one unified row to a decoration. |\n| `SplitLineDecorationProps` | Type | Supplies paired split rows to a decoration. |\n\n## Interaction manager\n\n| Export | Kind | Purpose |\n| ------------------------------- | -------- | ------------------------------------------------------------------------ |\n| `InteractionManager` | Class | Handles hover, token, gutter, and line selection events. |\n| `InteractionManagerMode` | Type | Selects file or diff interaction data. |\n| `InteractionManagerBaseOptions` | Type | Defines interaction callbacks and enabled features. |\n| `InteractionManagerOptions` | Type | Adds required DOM access to base interaction options. |\n| `GetHoveredLineResult` | Type | Describes the current hovered file or diff line. |\n| `GetLineIndexUtility` | Type | Maps a logical line to row and column indexes. |\n| `OnLineClickProps` | Type | Describes a file line click. |\n| `OnLineEnterLeaveProps` | Type | Describes file line pointer entry or exit. |\n| `OnDiffLineClickProps` | Type | Describes a diff line click. |\n| `OnDiffLineEnterLeaveProps` | Type | Describes diff line pointer entry or exit. |\n| `OnTokenEventProps` | Type | Selects file or diff token event data. |\n| `SelectionWriteOptions` | Type | Configures callback emission, the active side, and line-only highlights. |\n| `MergeConflictActionTarget` | Type | Describes a merge conflict action element. |\n| `LogTypes` | Type | Selects interaction log categories. |\n| `pluckInteractionOptions` | Function | Selects interaction fields from component options. |\n\n## Size, scroll, and render managers\n\n| Export | Kind | Purpose |\n| --------------------------------- | -------- | ------------------------------------------------------------- |\n| `ResizeManager` | Class | Measures rows, annotations, and column CSS values. |\n| `ResizeManagerColumnVariableMode` | Type | Selects column variable measurement or application. |\n| `ResizeManagerSetupOptions` | Type | Configures annotation and column measurement. |\n| `ScrollSyncManager` | Class | Synchronizes additions and deletions column scroll positions. |\n| `queueRender` | Function | Adds a callback to the shared animation render queue. |\n| `dequeueRender` | Function | Removes a callback from the shared render queue. |\n| `clearRenderQueue` | Function | Removes all callbacks from the shared render queue. |\n\n## Comparison helpers\n\n| Export | Purpose |\n| ----------------------------- | ------------------------------------------------- |\n| `areDiffLineAnnotationsEqual` | Compares two diff annotation arrays. |\n| `areLineAnnotationsEqual` | Compares two file annotation arrays. |\n| `areDiffRenderOptionsEqual` | Compares resolved diff render options. |\n| `areFileRenderOptionsEqual` | Compares resolved file render options. |\n| `areDiffTargetsEqual` | Compares two diff interaction targets. |\n| `areFilesEqual` | Compares two file inputs. |\n| `areHunkDataEqual` | Compares two hunk data objects. |\n| `areObjectsEqual` | Performs the package's shallow object comparison. |\n| `areOptionsEqual` | Compares component option objects. |\n| `arePrePropertiesEqual` | Compares calculated `pre` properties. |\n| `areRenderRangesEqual` | Compares two render ranges. |\n| `areSelectionsEqual` | Compares editor selection arrays. |\n| `areThemesEqual` | Compares theme names or light/dark pairs. |\n| `areVirtualWindowSpecsEqual` | Compares two virtual window descriptions. |\n| `areWorkerStatsEqual` | Compares two worker statistics objects. |\n\n## Syntax tree and DOM helpers\n\n| Export | Kind | Purpose |\n| -------------------------------- | -------- | ---------------------------------------------------------- |\n| `createAnnotationElement` | Function | Creates a HAST annotation row from an annotation span. |\n| `createAnnotationWrapperNode` | Function | Creates a DOM host for an annotation slot. |\n| `createDiffSpanDecoration` | Function | Creates one inline diff decoration. |\n| `pushOrJoinSpan` | Function | Adds or joins one inline diff span. |\n| `createEmptyRowBuffer` | Function | Creates an empty virtual row buffer. |\n| `createFileHeaderElement` | Function | Creates a file or diff header HAST element. |\n| `CreateFileHeaderElementProps` | Type | Defines header source, mode, and sticky state. |\n| `createGutterGap` | Function | Creates a gutter gap HAST element. |\n| `createGutterItem` | Function | Creates a gutter item HAST element. |\n| `createGutterWrapper` | Function | Creates a gutter wrapper HAST element. |\n| `createGutterUtilityElement` | Function | Creates a gutter utility HAST element. |\n| `createGutterUtilityContentNode` | Function | Creates a gutter utility DOM content host. |\n| `createHastElement` | Function | Creates a typed HAST element. |\n| `createIconElement` | Function | Creates a sprite icon HAST element. |\n| `createTextNodeElement` | Function | Creates a HAST text node. |\n| `createNoNewlineElement` | Function | Creates the missing-final-newline HAST element. |\n| `createPreElement` | Function | Creates the outer HAST `pre` element. |\n| `createPreWrapperProperties` | Function | Creates HAST properties for a `pre` wrapper. |\n| `createRowNodes` | Function | Creates DOM row and content elements for one line. |\n| `createSeparator` | Function | Creates a hunk separator HAST element. |\n| `createSpanFromToken` | Function | Creates a HAST span from one highlighted token. |\n| `createStyleElement` | Function | Creates a DOM style element with an attribute marker. |\n| `createThemeStyleElement` | Function | Creates a marked theme style element. |\n| `createUnsafeCSSStyleNode` | Function | Creates a marked custom CSS style element. |\n| `findCodeElement` | Function | Finds the code element in a HAST tree. |\n| `getLineNodes` | Function | Gets rendered line nodes from a HAST root. |\n| `getOrCreateCodeNode` | Function | Reuses or creates a code column DOM node. |\n| `getLineAnnotationName` | Function | Creates the slot name for a line annotation. |\n| `getHunkSeparatorSlotName` | Function | Creates the slot name for a hunk separator. |\n| `getIconForType` | Function | Maps a file change type to a sprite icon. |\n| `processLine` | Function | Applies line render state to one HAST line. |\n| `setPreNodeProperties` | Function | Applies resolved render properties to a DOM `pre` element. |\n| `prerenderHTMLIfNecessary` | Function | Adds preloaded HTML to an empty host element. |\n\n## Layout and CSS helpers\n\n| Export | Purpose |\n| -------------------------------- | ------------------------------------------------------------- |\n| `createWindowFromScrollPosition` | Calculates a virtual window from scroll measurements. |\n| `isDefaultRenderRange` | Tests whether a render range covers the default full range. |\n| `prefersReducedMotion` | Reads the reduced-motion media preference. |\n| `formatCSSVariablePrefix` | Creates the global or token CSS variable prefix. |\n| `wrapCoreCSS` | Places core CSS in its cascade layer. |\n| `wrapThemeCSS` | Places theme CSS in its layer and mode selector. |\n| `wrapUnsafeCSS` | Places custom CSS in its cascade layer. |\n| `patchScrollbarGutterSize` | Updates the measured scrollbar gutter in theme CSS. |\n| `detachString` | Copies a retained substring to an independent backing string. |\n| `releaseStringDetachBuffer` | Resets the reusable string copy buffer. |\n| `SVGSpriteSheet` | Contains the SVG symbols used by rendered controls. |\n| `SVGSpriteNames` | Names a symbol in `SVGSpriteSheet`. |\n\n## Constants\n\n| Export | Purpose |\n| ------------------------------------------ | ----------------------------------------------------- |\n| `DEFAULT_THEMES` | Provides the default light and dark theme names. |\n| `DEFAULT_TOKENIZE_MAX_LENGTH` | Provides the default total tokenization limit. |\n| `DEFAULT_COLLAPSED_CONTEXT_THRESHOLD` | Provides the default hidden-context threshold. |\n| `DEFAULT_EXPANDED_REGION` | Provides the default hunk expansion state. |\n| `DEFAULT_RENDER_RANGE` | Provides the full render range. |\n| `EMPTY_RENDER_RANGE` | Provides an empty render range. |\n| `DEFAULT_VIRTUAL_FILE_METRICS` | Provides estimated file header and line heights. |\n| `DEFAULT_CODE_VIEW_FILE_METRICS` | Provides list item height estimates. |\n| `DEFAULT_CODE_VIEW_LAYOUT` | Provides an empty list layout. |\n| `DEFAULT_SMOOTH_SCROLL_SETTINGS` | Provides the default smooth scroll settings. |\n| `DIFFS_TAG_NAME` | Provides the `diffs-container` custom element name. |\n| `CORE_CSS_ATTRIBUTE` | Provides the core style marker attribute. |\n| `THEME_CSS_ATTRIBUTE` | Provides the theme style marker attribute. |\n| `UNSAFE_CSS_ATTRIBUTE` | Provides the custom style marker attribute. |\n| `DIFFS_SCROLLBAR_MEASURE_ATTRIBUTE` | Provides the scrollbar measurement attribute. |\n| `DIFFS_SCROLLBAR_GUTTER_MEASURED_PROPERTY` | Provides the measured scrollbar CSS property. |\n| `CODE_VIEW_HEADER_ATTRIBUTE` | Provides the list header host attribute. |\n| `CODE_VIEW_FOOTER_ATTRIBUTE` | Provides the list footer host attribute. |\n| `CUSTOM_HEADER_SLOT_ID` | Provides the custom header slot ID. |\n| `HEADER_PREFIX_SLOT_ID` | Provides the header prefix slot ID. |\n| `HEADER_FILENAME_SUFFIX_SLOT_ID` | Provides the filename suffix slot ID. |\n| `HEADER_METADATA_SLOT_ID` | Provides the header metadata slot ID. |\n| `HUNK_HEADER` | Provides the patch hunk header marker. |\n| `FILE_CONTEXT_BLOB` | Matches a patch hunk boundary. |\n| `INDEX_LINE_METADATA` | Provides the patch index metadata marker. |\n| `COMMIT_METADATA_SPLIT` | Provides the commit metadata separator expression. |\n| `FILENAME_HEADER_REGEX` | Matches a standard patch file header. |\n| `GIT_DIFF_FILE_BREAK_REGEX` | Matches a Git patch file boundary. |\n| `UNIFIED_DIFF_FILE_BREAK_REGEX` | Matches a unified patch file boundary. |\n| `MERGE_CONFLICT_START_MARKER_REGEX` | Matches a conflict start marker. |\n| `MERGE_CONFLICT_BASE_MARKER_REGEX` | Matches a conflict base marker. |\n| `MERGE_CONFLICT_SEPARATOR_MARKER_REGEX` | Matches a conflict separator marker. |\n| `MERGE_CONFLICT_END_MARKER_REGEX` | Matches a conflict end marker. |\n| `SPLIT_WITH_NEWLINES` | Splits text while it preserves newline tokens. |\n| `DIFFS_DEVELOPMENT_BUILD` | Reports whether the package uses a development build. |\n\n\n# SSR API\n\nThis reference lists the SSR-specific exports from `@pierre/diffs/ssr`. The\nentry also re-exports every type in [Shared types](api-types.md).\n\n## Functions\n\n| Export | Purpose |\n| --------------------------- | ------------------------------------------------------------- |\n| `preloadFile` | Renders one file and returns props with `prerenderedHTML`. |\n| `preloadFileDiff` | Renders pre-parsed diff metadata and returns component props. |\n| `preloadMultiFileDiff` | Parses and renders an old and new file pair. |\n| `preloadPatchDiff` | Parses and renders one patch for `PatchDiff`. |\n| `preloadPatchFile` | Parses a multi-file patch and returns one result per file. |\n| `preloadUnresolvedFile` | Renders one merge-conflict file and returns component props. |\n| `preloadDiffHTML` | Renders a diff directly to an HTML string. |\n| `preloadUnresolvedFileHTML` | Renders a merge-conflict file directly to an HTML string. |\n| `renderHTML` | Serializes rendered HAST elements to HTML. |\n\n## Types\n\n| Export | Purpose |\n| ------------------------------ | -------------------------------------------------------- |\n| `PreloadFileOptions` | Defines input for `preloadFile`. |\n| `PreloadedFileResult` | Adds `prerenderedHTML` to file input. |\n| `PreloadDiffOptions` | Defines parsed or file-pair input for `preloadDiffHTML`. |\n| `PreloadFileDiffOptions` | Defines input for `preloadFileDiff`. |\n| `PreloadFileDiffResult` | Adds `prerenderedHTML` to parsed diff input. |\n| `PreloadMultiFileDiffOptions` | Defines input for `preloadMultiFileDiff`. |\n| `PreloadMultiFileDiffResult` | Adds `prerenderedHTML` to file-pair input. |\n| `PreloadPatchDiffOptions` | Defines input for `preloadPatchDiff`. |\n| `PreloadPatchDiffResult` | Adds `prerenderedHTML` to patch input. |\n| `PreloadPatchFileOptions` | Defines input for `preloadPatchFile`. |\n| `PreloadUnresolvedFileOptions` | Defines input for `preloadUnresolvedFile`. |\n| `PreloadUnresolvedFileResult` | Adds `prerenderedHTML` to merge-conflict input. |\n\n\n# Shared types\n\nThis reference lists every export from the shared `@pierre/diffs` type module.\nThe root, React, and SSR entries re-export these types.\n\n## Contents\n\n- [Files and patches](#files-and-patches)\n- [Themes and options](#themes-and-options)\n- [Annotations and selection](#annotations-and-selection)\n- [`CodeView` types](#codeview-types)\n- [Lines, hunks, and render state](#lines-hunks-and-render-state)\n- [Render results and virtualization](#render-results-and-virtualization)\n- [Tokenization and diff types](#tokenization-and-diff-types)\n\n## Files and patches\n\n| Export | Purpose |\n| ------------------------------- | ----------------------------------------------------------------- |\n| `FileContents` | Describes a file name, text, language, header, and cache key. |\n| `DiffFileInput` | Accepts an old and new file for changes, additions, or deletions. |\n| `MaybeDiffFileInput` | Accepts a file pair or no file input. |\n| `FileDiffContentsLoader` | Loads complete files for partial diff metadata. |\n| `FileDiffLoadedChangedFiles` | Returns both files for a loaded changed diff. |\n| `FileDiffLoadedPureRenamedFile` | Returns the new file for a loaded pure rename. |\n| `FileDiffLoadedFiles` | Represents either loaded-file result. |\n| `ChangeTypes` | Names changed, renamed, added, or deleted file states. |\n| `ParsedPatch` | Holds patch metadata and parsed files. |\n| `ContextContent` | Describes one unchanged hunk block. |\n| `ChangeContent` | Describes one additions and deletions block. |\n| `Hunk` | Describes one parsed patch hunk. |\n| `FileDiffMetadata` | Holds parsed file names, lines, hunks, and change metadata. |\n| `MergeConflictMarkerRowType` | Names a merge conflict marker row. |\n| `MergeConflictMarkerRow` | Describes one marker row and its source line. |\n| `MergeConflictRegion` | Describes one parsed merge conflict region. |\n| `MergeConflictResolution` | Selects current, incoming, or both conflict contents. |\n| `MergeConflictActionPayload` | Describes one conflict action and region. |\n| `ProcessFileConflictData` | Holds state while patch parsing processes conflicts. |\n| `ConflictResolverTypes` | Names current, incoming, or both conflict choices. |\n\n## Themes and options\n\n| Export | Purpose |\n| ------------------------------------ | -------------------------------------------------------------- |\n| `SupportedLanguages` | Accepts a bundled, text, ANSI, or custom language name. |\n| `HighlighterTypes` | Selects shiki-js, shiki-wasm, or highlights. |\n| `HighlightedToken` | Stores a character index, foreground, and token text. |\n| `DiffsThemeNames` | Accepts a bundled or custom theme name. |\n| `ThemesType` | Maps light and dark schemes to theme names. |\n| `ThemeTypes` | Selects system, light, or dark mode. |\n| `DiffsHighlighter` | Defines backend-independent tokenization and theme resolution. |\n| `BaseCodeOptions` | Configures themes, wrapping, headers, tokenization, and CSS. |\n| `BaseDiffOptions` | Adds layout, indicators, context, and line diff options. |\n| `BaseDiffOptionsWithDefaults` | Describes required diff options after defaults apply. |\n| `DiffIndicators` | Selects classic, bar, or hidden diff indicators. |\n| `HunkSeparators` | Selects the hunk separator presentation. |\n| `LineDiffTypes` | Selects word, alternate word, character, or no inline diff. |\n| `FileHeaderRenderMode` | Selects a default or custom file header. |\n| `CustomPreProperties` | Defines custom properties for the rendered `pre` element. |\n| `PrePropertiesConfig` | Describes calculated `pre` element properties. |\n| `ExtensionFormatMap` | Maps file names or extensions to languages. |\n| `RenderHeaderPrefixCallback` | Produces prefix content for a diff header. |\n| `RenderHeaderFilenameSuffixCallback` | Produces filename suffix content for a diff header. |\n| `RenderHeaderMetadataCallback` | Produces metadata content for a diff header. |\n| `RenderFileMetadata` | Produces header content for a file. |\n| `PostRenderPhase` | Names mount, update, or unmount callback phases. |\n\n## Annotations and selection\n\n| Export | Purpose |\n| -------------------- | ----------------------------------------------------- |\n| `AnnotationSide` | Selects deletions or additions for an annotation. |\n| `LineAnnotation` | Associates metadata with one file line. |\n| `DiffLineAnnotation` | Associates metadata with one side and line. |\n| `AnnotationLineMap` | Groups diff annotations by line number. |\n| `SelectedLineRange` | Describes a selected start and end across diff sides. |\n| `SelectionSide` | Selects deletions or additions for a selection. |\n| `SelectionPoint` | Describes one line and optional side. |\n\n## `CodeView` types\n\n| Export | Purpose |\n| --------------------------------- | -------------------------------------------------------- |\n| `CodeViewFileItem` | Describes one file item in a virtualized list. |\n| `CodeViewDiffItem` | Describes one diff item in a virtualized list. |\n| `CodeViewItem` | Represents a file or diff list item. |\n| `CodeViewCreateEditorOptions` | Provides CodeView's routed editor option subset. |\n| `CodeViewItemEditCompleteHandler` | Handles completion with correlated event and item types. |\n| `CodeViewScrollBehavior` | Selects instant, smooth, or automatic smooth scroll. |\n| `CodeViewScrollTarget` | Represents any supported list scroll target. |\n| `CodeViewPositionScrollTarget` | Scrolls to an absolute list position. |\n| `CodeViewLineScrollTarget` | Scrolls to one item line. |\n| `CodeViewRangeScrollTarget` | Scrolls to one item line range. |\n| `CodeViewItemScrollTarget` | Scrolls to one item boundary. |\n| `NumericScrollLineAnchor` | Describes a numeric position inside a line. |\n| `CodeViewLayout` | Stores item offsets, heights, and total list height. |\n| `PendingCodeViewLayoutReset` | Describes a deferred list layout reset. |\n| `SmoothScrollSettings` | Configures duration and distance for smooth list scroll. |\n\n`CodeViewCreateEditorOptions` currently contains the routed `onChange(event)`\ncallback that `CodeView` uses to emit `onItemEditChange(event, item)`; it does\nnot add an item ID. A `CodeViewOptions.createEditor` factory also receives the\noptional `editStateKey` returned by `getEditStateKey(item)` as its third\nargument. Forward that key separately to the editor constructor. It retains the\neditable draft, undo/redo history, selections, and horizontal code scroll. Item\neditors never own CodeView's shared vertical position.\n\n`onItemEditComplete(event, item, nextItem)` must return `'accept'` to accept the\ncompleted item or `'reject'` to restore the original while the item remains\npresent; a missing callback rejects. During removal or teardown, neither\ndecision reinserts the item. Controlled owners must put the supplied `nextItem`\ninto their item state when accepting an item that should remain. If the item\nuses keyed render caching, assigning a fresh `cacheKey` to the accepted event\nfile or diff invalidates that cache.\n\n## Lines, hunks, and render state\n\n| Export | Purpose |\n| ---------------------------- | --------------------------------------------------------------- |\n| `HunkLineType` | Names context, expanded, addition, deletion, or metadata lines. |\n| `HunkData` | Describes one hunk's render indexes and line ranges. |\n| `HunkExpansionRegion` | Describes expanded context above and below a hunk. |\n| `ExpansionDirections` | Selects up, down, or both expansion directions. |\n| `DiffAcceptRejectHunkType` | Selects accept, reject, or both hunk controls. |\n| `DiffAcceptRejectHunkConfig` | Configures hunk accept and reject behavior. |\n| `GapSpan` | Describes an empty row span. |\n| `AnnotationSpan` | Describes an annotation row span. |\n| `LineSpans` | Represents a gap or annotation span. |\n| `LineTypes` | Names rendered context and change line classes. |\n| `LineInfo` | Describes a rendered line number, side, and type. |\n| `CodeColumnType` | Selects unified, additions, or deletions columns. |\n| `LineEventBaseProps` | Supplies a file line to an interaction callback. |\n| `DiffLineEventBaseProps` | Supplies a diff line and side to an interaction callback. |\n| `TokenEventBase` | Supplies a token and source event. |\n| `DiffTokenEventBaseProps` | Adds diff side data to a token event. |\n| `ObservedAnnotationNodes` | Stores DOM nodes for observed annotations. |\n| `ObservedGridNodes` | Stores DOM nodes for observed grid columns. |\n| `SharedRenderState` | Holds shared token transformer render state. |\n| `StickySpecs` | Describes sticky header position and height. |\n\n## Render results and virtualization\n\n| Export | Purpose |\n| --------------------------- | ------------------------------------------------------- |\n| `RenderFileOptions` | Defines the resolved options for a highlighted file. |\n| `RenderDiffOptions` | Defines the resolved options for a highlighted diff. |\n| `ForceFilePlainTextOptions` | Selects a plain-text file range. |\n| `ForceDiffPlainTextOptions` | Selects a plain-text diff range and hunk state. |\n| `ThemedFileResult` | Holds the highlighted file syntax tree and line count. |\n| `ThemedDiffResult` | Holds highlighted additions and deletions syntax trees. |\n| `RenderDiffFilesResult` | Holds the resolved old and new file inputs. |\n| `RenderFileResult` | Holds file output and the options that produced it. |\n| `RenderDiffResult` | Holds diff output and the options that produced it. |\n| `RenderedFileASTCache` | Stores one cached file syntax tree by theme. |\n| `RenderedDiffASTCache` | Stores one cached diff syntax tree by theme. |\n| `AppliedThemeStyleCache` | Stores applied light and dark theme CSS. |\n| `RenderRange` | Describes a start row, row count, and buffer sizes. |\n| `RenderWindow` | Describes first and last rows in a render window. |\n| `VirtualWindowSpecs` | Describes viewport position, height, and row window. |\n| `VirtualFileMetrics` | Describes estimated header and line heights. |\n\n## Tokenization and diff types\n\n| Export | Purpose |\n| ----------------------------------------------------- | -------------------------------------------------------------------- |\n| `DiffsTheme` | Shared editor colors with optional TextMate and Zed syntax palettes. |\n| `ThemedToken` | One styled token with content, offset, color, and optional styles. |\n| `TokensResult` | Token rows and root colors/styles. |\n| `CodeToTokensOptions`, `CodeToHtmlOptions` | Select a language, themes, and tokenization limits. |\n| `DiffsStreamTokenizer` | Incremental tokenization of appended chunks. |\n| `DiffsEditorTokenizer`, `DiffsEditorTokenizerOptions` | Incremental tokenization of document edits. |\n| `CreatePatchOptionsNonabortable` | Configures the underlying patch algorithm. |\n\nImport TextMate registration and Shiki transformer types from `shiki`. Diffs no\nlonger re-exports Shiki's public API.\n\n\n# Worker API\n\nThis reference lists every export from `@pierre/diffs/worker`, every public\n`WorkerPoolManager` member, and both worker script entries.\n\n## Runtime exports\n\n| Export | Kind | Purpose |\n| -------------------------------- | -------- | ----------------------------------------------------- |\n| `WorkerPoolManager` | Class | Runs file and diff highlighting across a worker pool. |\n| `getOrCreateWorkerPoolSingleton` | Function | Gets or creates the module-wide worker pool. |\n| `terminateWorkerPoolSingleton` | Function | Terminates and clears the module-wide worker pool. |\n\n## `WorkerPoolManager` members\n\n| Member | Purpose |\n| -------------------------------------------------------------- | ------------------------------------------------- |\n| `new WorkerPoolManager(options, renderOptions)` | Creates a worker pool. |\n| `initialize(languages?)` | Starts workers and loads languages. |\n| `isInitialized()` | Reports whether initialization finished. |\n| `isWorkingPool()` | Reports whether workers can accept work. |\n| `setRenderOptions(options)` | Updates theme and render settings in each worker. |\n| `getFileRenderOptions()` | Gets active file render options. |\n| `getDiffRenderOptions()` | Gets active diff render options. |\n| `highlightFileAST(instance, file)` | Queues a highlighted file result for an instance. |\n| `highlightDiffAST(instance, diff)` | Queues a highlighted diff result for an instance. |\n| `primeFileHighlightCache(file)` | Preloads one highlighted file result. |\n| `primeDiffHighlightCache(diff)` | Preloads one highlighted diff result. |\n| `getFileResultCache(file)` | Gets one cached file result. |\n| `getDiffResultCache(diff)` | Gets one cached diff result. |\n| `getPlainFileAST(file, start, total, lines?)` | Gets a plain-text file result. |\n| `getPlainDiffAST(diff, start, total, expansions?, threshold?)` | Gets a plain-text diff result. |\n| `inspectCaches()` | Gets both result caches. |\n| `evictFileFromCache(cacheKey)` | Removes one file cache entry. |\n| `evictDiffFromCache(cacheKey)` | Removes one diff cache entry. |\n| `subscribeToThemeChanges(instance)` | Subscribes a render instance to theme changes. |\n| `unsubscribeToThemeChanges(instance)` | Removes a theme subscription. |\n| `subscribeToStatChanges(callback)` | Subscribes to worker statistics. |\n| `cleanUpTasks(instance)` | Removes queued and active tasks for an instance. |\n| `getStats()` | Gets worker and cache statistics. |\n| `terminate()` | Stops workers and clears pool resources. |\n\n## Configuration and state types\n\n| Export | Purpose |\n| ----------------------------------- | ----------------------------------------------------------------- |\n| `SetupWorkerPoolProps` | Combines pool and highlighter options for the singleton. |\n| `WorkerPoolOptions` | Defines the worker factory, pool size, and cache size. |\n| `WorkerInitializationRenderOptions` | Defines initial languages, theme, highlighter, and diff settings. |\n| `WorkerRenderingOptions` | Defines the complete worker render settings. |\n| `WorkerStats` | Describes pool state, work counts, subscribers, and cache sizes. |\n| `WorkerRequestId` | Identifies one worker request. |\n| `ResolvedLanguage` | Holds a resolved language registration. |\n| `FileRendererInstance` | Defines callbacks for a file render consumer. |\n| `DiffRendererInstance` | Defines callbacks for a diff render consumer. |\n\n## Request and response types\n\n| Export | Purpose |\n| ------------------------------- | ------------------------------------------------------- |\n| `WorkerRequest` | Represents any request sent to a worker. |\n| `InitializeWorkerRequest` | Starts a worker with themes, languages, and options. |\n| `SetRenderOptionsWorkerRequest` | Updates render options and themes. |\n| `RenderFileRequest` | Requests one file render. |\n| `RenderDiffRequest` | Requests one diff render. |\n| `SubmitRequest` | Represents a file or diff request before ID assignment. |\n| `WorkerResponse` | Represents any worker response. |\n| `InitializeSuccessResponse` | Confirms worker initialization. |\n| `RegisterThemeSuccessResponse` | Confirms a render-option and theme update. |\n| `RenderSuccessResponse` | Represents a successful file or diff render. |\n| `RenderFileSuccessResponse` | Returns one file render result. |\n| `RenderDiffSuccessResponse` | Returns one diff render result. |\n| `RenderErrorResponse` | Returns a serialized worker error. |\n\n## Task types\n\n| Export | Purpose |\n| ---------------------------- | ------------------------------------------------- |\n| `AllWorkerTasks` | Represents any manager task. |\n| `InitializeWorkerTask` | Tracks one initialization request. |\n| `SetRenderOptionsWorkerTask` | Tracks one render-option update. |\n| `RenderFileTask` | Tracks one file render request and its consumers. |\n| `RenderDiffTask` | Tracks one diff render request and its consumers. |\n| `RenderTaskCallbacks` | Resolves or rejects one render task consumer. |\n\n## Worker script entries\n\n| Import | Purpose |\n| ----------------------------------------- | -------------------------------------------------------------------------------- |\n| `@pierre/diffs/worker/worker.js` | Supplies the module worker that uses package dependencies. |\n| `@pierre/diffs/worker/worker-portable.js` | Supplies a single script with all highlighter backends and dependencies bundled. |\n\nFor static hosting, copy `dist/worker/worker-portable.js` and start it with\n`new Worker(url)`. It also supports module workers and blob URLs, including VS\nCode webviews, without another bundling step. All backends are included in the\ndownload; only the selected backend is initialized. For lazy backend loading,\nuse the regular worker entry with your bundler.\n\nThe pool resolves themes and Shiki grammars on the main thread and sends them to\nthe worker. Their catalogs are excluded from the portable script.\n\nA pool is optional. When one is supplied, highlighting goes through its workers\nfor every backend. Highlights is often fast enough on the main thread to skip\nthe pool.\n\n\n# Recipe: add line annotations and selection\n\nPass annotation data and a renderer to the surface:\n\n```tsx\nimport type { DiffLineAnnotation } from '@pierre/diffs/react';\nimport { MultiFileDiff } from '@pierre/diffs/react';\n\nconst annotations: DiffLineAnnotation<{ message: string }>[] = [\n {\n side: 'additions',\n lineNumber: 8,\n metadata: { message: 'Review this line.' },\n },\n];\n\n

{annotation.metadata.message}

}\n options={{\n enableLineSelection: true,\n onLineSelectionEnd(range) {\n saveSelection(range);\n },\n }}\n/>;\n```\n\nUse `LineAnnotation` for a single file. Use `DiffLineAnnotation` for a diff.\nControl the active selection with the `selectedLines` prop.\n\n\n# Recipe: build a `CodeView`\n\nUse `CodeView` when one scroll region contains many files, diffs, or both. It\nmanages item virtualization, sticky headers, list-wide selection, and item or\nline scroll targets.\n\n## Contents\n\n- [Select item ownership](#select-item-ownership)\n- [Define items](#define-items)\n- [Use controlled React state](#use-controlled-react-state)\n- [Use imperative ownership](#use-imperative-ownership)\n- [Enable item edit mode](#enable-item-edit-mode)\n\n## Select item ownership\n\n| Host and data flow | Input | Update API |\n| ------------------------------------------- | ----------------- | ------------------------------------ |\n| React owns the complete list | `items` | Publish a new `items` array. |\n| React hosts a large or append-only list | `initialItems` | Use the `CodeViewHandle` methods. |\n| Vanilla JavaScript owns the viewer instance | `setItems(items)` | Use the `CodeView` instance methods. |\n\nKeep one ownership mode for the life of a mounted React viewer. Use controlled\nstate when item data already belongs to React. Use imperative ownership for a\nlarge or streamed list.\n\n## Define items\n\nGive each item a stable and unique `id`. Use a `file` item for `FileContents`.\nUse a `diff` item for `FileDiffMetadata`.\n\nIncrement `version` when an existing item changes its contents, annotations,\ncollapsed state, or edit state. `CodeView` uses the ID and version to select the\nitem that it must update.\n\n## Use controlled React state\n\n```tsx\nimport {\n parseDiffFromFile,\n type CodeViewItem,\n type CodeViewLineSelection,\n} from '@pierre/diffs';\nimport { CodeView, type CodeViewHandle } from '@pierre/diffs/react';\nimport { useRef, useState } from 'react';\n\nconst oldFile = {\n name: 'src/value.ts',\n contents: 'export const value = 1;',\n};\nconst newFile = {\n name: 'src/value.ts',\n contents: 'export const value = 2;',\n};\nconst codeViewStyle = { height: 600, overflow: 'auto' } as const;\nconst codeViewOptions = {\n theme: { light: 'pierre-light', dark: 'pierre-dark' },\n stickyHeaders: true,\n enableLineSelection: true,\n layout: { paddingTop: 16, paddingBottom: 16, gap: 12 },\n} as const;\n\nexport function ReviewSurface() {\n const viewerRef = useRef | null>(null);\n const [selection, setSelection] = useState(\n null\n );\n const [items, setItems] = useState(() => [\n {\n id: 'diff:src/value.ts',\n type: 'diff',\n fileDiff: parseDiffFromFile(oldFile, newFile),\n version: 0,\n },\n {\n id: 'file:README.md',\n type: 'file',\n file: { name: 'README.md', contents: '# Review notes' },\n version: 0,\n },\n ]);\n\n function toggleDiff() {\n setItems((current) =>\n current.map((item) =>\n item.id === 'diff:src/value.ts'\n ? {\n ...item,\n collapsed: !item.collapsed,\n version: (item.version ?? 0) + 1,\n }\n : item\n )\n );\n }\n\n return (\n <>\n \n \n viewerRef.current?.scrollTo({\n type: 'line',\n id: 'diff:src/value.ts',\n lineNumber: 1,\n side: 'additions',\n align: 'center',\n })\n }\n >\n Jump to change\n \n \n \n );\n}\n```\n\n## Use imperative ownership\n\nIn React, pass `initialItems` and keep `items` unset. Use the component ref to\ncall `addItems`, `getItem`, `updateItem`, `updateItemId`, or `scrollTo`.\n\nIn vanilla JavaScript, configure and populate the instance directly:\n\n```ts\nimport { CodeView, parseDiffFromFile } from '@pierre/diffs';\n\nconst root = document.querySelector('#review');\nif (root == null) throw new Error('Missing review host');\n\nconst oldFile = {\n name: 'src/value.ts',\n contents: 'export const value = 1;',\n};\nconst newFile = {\n name: 'src/value.ts',\n contents: 'export const value = 2;',\n};\n\nconst viewer = new CodeView({\n theme: { light: 'pierre-light', dark: 'pierre-dark' },\n stickyHeaders: true,\n enableLineSelection: true,\n onSelectedLinesChange(selection) {\n console.log('selected lines', selection);\n },\n});\n\nroot.style.height = '600px';\nroot.style.overflow = 'auto';\nviewer.setup(root);\nviewer.setItems([\n {\n id: 'diff:src/value.ts',\n type: 'diff',\n fileDiff: parseDiffFromFile(oldFile, newFile),\n version: 0,\n },\n]);\n\nviewer.addItems([\n {\n id: 'file:README.md',\n type: 'file',\n file: { name: 'README.md', contents: '# Review notes' },\n version: 0,\n },\n]);\nviewer.scrollTo({\n type: 'item',\n id: 'diff:src/value.ts',\n align: 'start',\n});\n\nconst item = viewer.getItem('diff:src/value.ts');\nif (item != null) {\n viewer.updateItem({\n ...item,\n collapsed: true,\n version: (item.version ?? 0) + 1,\n });\n}\n\nexport function removeReviewSurface() {\n viewer.cleanUp();\n}\n```\n\n## Enable item edit mode\n\nIn React, wrap `CodeView` in `EditProvider`. In vanilla JavaScript, pass\n`createEditor(editorType, options, editStateKey)` in `CodeViewOptions` and\nforward all three arguments to `new Editor`. Set `edit: true` on each editable\nitem and increment its version. The factory receives `'file'` or `'file-diff'`\nas its first argument so it can construct an editor of the requested type.\n\n`onItemEditChange(event, item)` reports live contents and annotation changes.\nRead the current document from `event.file`, the complete annotation collection\nfrom `event.lineAnnotations`. Treat it as a notification and do not feed the\nchanges back into the viewer.\n\n`onItemEditComplete(event, item, nextItem)` must return `'accept'` or `'reject'`\nwhenever a session ends, including when its final text is unchanged. `CodeView`\nbuilds `nextItem` with the completed contents and annotations, `edit: false`,\nand an incremented `version`. If you use keyed render caching, assign a fresh\n`cacheKey` to `event.file` or `event.fileDiff` before accepting. Return\n`'accept'` to install `nextItem` while the item remains present, or `'reject'`\nto restore the original item while it remains present. During removal or viewer\nteardown, neither decision reinserts the item. A missing callback rejects. When\nReact controls `items`, put `nextItem` into controlled state only when the item\nshould remain.\n\nUse `getEditStateKey(item)` to opt into retaining the draft, undo/redo history,\nselections, and editor-owned view state across editor instances. The returned\n`editStateKey` is passed to the editor factory. `getEditor(id)` returns the\ncurrent `Editor` instance.\n\nRead [Edit with React](recipe-edit-react.md) or\n[Edit with vanilla JavaScript](recipe-edit-vanilla.md) for the complete editor\nlifecycle.\n\n\n# Recipe: register custom highlighting\n\nRegister themes before rendering. For a Zed-compatible theme with Highlights:\n\n```tsx\nimport { registerCustomTheme } from '@pierre/diffs';\nimport { FileDiff } from '@pierre/diffs/react';\n\nregisterCustomTheme('app-dark', () => import('./my-zed-theme.json'), 'zed');\n\n;\n```\n\nFor TextMate themes and custom grammars, use Shiki:\n\n```ts\nimport { registerCustomLanguage, registerCustomTheme } from '@pierre/diffs';\n\nregisterCustomLanguage(\n 'my-language',\n () => import('./my-language.tmLanguage.json'),\n ['myext']\n);\nregisterCustomTheme('my-theme', () => import('./my-textmate-theme.json'));\n```\n\nSet `file.lang` and `options.theme` to the registered names. Custom languages\napply to Shiki; Highlights bundles its lexers and ignores custom grammars.\n\nFor a CSS palette that works across backends:\n\n```ts\nimport { registerCustomCSSVariableTheme } from '@pierre/diffs';\n\nregisterCustomCSSVariableTheme('app-palette', {\n foreground: '#eeeeee',\n background: '#101010',\n 'token-keyword': '#c084fc',\n 'token-string-expression': '#86efac',\n});\n```\n\nThis registers a shared Diffs theme using `--diffs-*` variables. See\n[Highlighting API](api-highlighting.md#themes) for loader formats, name\nmatching, and CSS palette options.\n\n\n# Recipe: edit with React\n\nMount one `EditProvider` above the editable surfaces. Its factory receives the\neditor type, the surface's creation-time `editorOptions`, and an optional\n`editStateKey`. Each active surface or `CodeView` item owns its editor.\n\nPass `editStateKey` to opt into bounded in-memory retention of the draft,\nundo/redo history, selections, horizontal scroll, eligible vertical scroll, and\ndiff resume metadata across editor instances. Choose this key explicitly; it is\na stable application identity for the document. The same active key cannot be\nshared by two editors of the same type.\n\n## Contents\n\n- [Edit a standalone file or diff](#edit-a-standalone-file-or-diff)\n- [Keep annotations synchronized](#keep-annotations-synchronized)\n- [Edit CodeView items](#edit-codeview-items)\n\n## Edit a standalone file or diff\n\nSet `edit` on `File`, `FileDiff`, `MultiFileDiff`, or `PatchDiff`. Pass editor\ncreation options through `editorOptions` and optional retention through\n`editStateKey`.\n\n```tsx\nimport type { FileContents, FileDiffOptions } from '@pierre/diffs';\nimport {\n Editor,\n type EditorChangeEvent,\n type EditorFactory,\n type EditorOptions,\n type FileDiffEditCompleteEvent,\n} from '@pierre/diffs/edit';\nimport { EditProvider, MultiFileDiff, Virtualizer } from '@pierre/diffs/react';\nimport { useMemo, useRef, useState } from 'react';\n\nconst oldFile: FileContents = {\n name: 'src/value.ts',\n contents: 'export const value = 1;',\n};\nconst initialNewFile: FileContents = {\n name: 'src/value.ts',\n contents: 'export const value = 2;',\n};\nconst diffOptions: FileDiffOptions = {\n theme: { light: 'pierre-light', dark: 'pierre-dark' },\n diffStyle: 'split',\n};\n\nconst createEditor: EditorFactory = (\n editorType,\n options,\n editStateKey?: string\n) => new Editor(editorType, options, editStateKey);\n\nexport function EditableDiff() {\n const [edit, setEdit] = useState(false);\n const [newFile, setNewFile] = useState(initialNewFile);\n const editorRef = useRef | null>(null);\n const editorOptions = useMemo<\n EditorOptions<'file-diff', undefined, undefined>\n >(\n () => ({\n onAttach(editor) {\n editorRef.current = editor;\n },\n }),\n []\n );\n\n function toggleEdit() {\n setEdit((value) => !value);\n }\n\n function handleEditChange(\n event: EditorChangeEvent<'file-diff', undefined, undefined>\n ) {\n saveDraft(event.file);\n }\n\n function handleEditComplete(\n event: FileDiffEditCompleteEvent\n ) {\n if (event.newFile != null) {\n setNewFile(event.newFile);\n }\n return 'accept' as const;\n }\n\n return (\n \n \n editorRef.current?.undo()}\n >\n Undo\n \n \n \n \n \n );\n}\n```\n\nMount the provider near the application root when many surfaces use edit mode.\nAlways forward all three factory arguments. Use `onAttach` when controls need\n`undo`, `redo`, `applyEdits`, selections, markers, focus, or other editor APIs.\n`EditStateManager` only manages sessions retained with `editStateKey`; unkeyed\nsessions require no manager cleanup. For keyed sessions, use\n`EditStateManager.clear(type, key)` after a session becomes inactive when its\nretained draft should be discarded. `clearAll()` clears inactive state in both\nnamespaces, and `setCapacity(capacity)` changes each namespace's default limit\nof 100 entries. Active state is never mutated by manager clearing.\n\n## Keep annotations synchronized\n\nEdit mode owns annotation positions during an active session. Change events\nexpose the remapped collection for observation, but do not feed it back into the\nsurface. On acceptance, store the completion event's final annotations beside\nthe accepted file or diff. Use `isFileAnnotationCollection` or\n`isDiffAnnotationCollection` when the surface type is not already known, and key\nannotation UI state by a stable metadata ID instead of a line number.\n\n## Edit `CodeView` items\n\nWrap `CodeView` in the same `EditProvider`. Set `edit: true` on an item and\nincrement its `version`. Pass shared creation options through the `CodeView`\n`editorOptions` prop. Use `getEditStateKey(item)` for opt-in draft, history,\nselection, and view-state retention.\n\nUse `onItemEditChange` for live contents and annotation changes. Use\n`onItemEditComplete` to accept or reject every ended session, including when its\nfinal text is unchanged. If you use keyed render caching, assign a fresh\n`cacheKey` to the event's file or diff. Put the supplied `nextItem` into\ncontrolled state only while the item should remain, then return `'accept'`;\nacceptance during removal or teardown does not reinsert it. `CodeView` builds\n`nextItem` with `edit: false` and an incremented `version`.\n\n`CodeViewHandle.getEditor(id)` returns the current `Editor` instance. The item\neditor keeps its active document and history when virtualization or collapse\nremoves the item from the rendered window. `getEditStateKey` extends that\nretention to later editor instances after the edit session ends.\n\nWhen a worker pool highlights an editable surface, set\n`useTokenTransformer: true` in the worker `highlighterOptions`.\n\n\n# Recipe: edit with vanilla JavaScript\n\nRender a standalone surface first. Then attach one `Editor` to it. Use one\neditor for each surface that can be edited at the same time.\n\n## Contents\n\n- [Edit a standalone diff](#edit-a-standalone-diff)\n- [Edit CodeView items](#edit-codeview-items)\n\n## Edit a standalone diff\n\n```ts\nimport {\n FileDiff,\n type DiffLineAnnotation,\n type FileContents,\n} from '@pierre/diffs';\nimport { Editor } from '@pierre/diffs/edit';\n\ninterface ThreadMetadata {\n id: string;\n}\n\nconst hostElement = document.querySelector('#diff');\nif (hostElement == null) throw new Error('Missing diff host');\nconst host: HTMLElement = hostElement;\n\nconst oldFile: FileContents = {\n name: 'src/value.ts',\n contents: 'export const value = 1;',\n};\nlet newFile: FileContents = {\n name: 'src/value.ts',\n contents: 'export const value = 2;',\n};\nlet annotations: DiffLineAnnotation[] = [\n {\n side: 'additions',\n lineNumber: 1,\n metadata: { id: 'value-review' },\n },\n];\nconst view = new FileDiff({\n theme: { light: 'pierre-light', dark: 'pierre-dark' },\n onEditChange(event) {\n saveDraft(event.file);\n },\n onEditComplete(event) {\n if (event.newFile != null) {\n newFile = event.newFile;\n }\n if (event.lineAnnotations != null) {\n annotations = event.lineAnnotations;\n }\n return 'accept';\n },\n renderAnnotation(annotation) {\n const element = document.createElement('p');\n element.textContent = 'Thread ' + annotation.metadata.id;\n return element;\n },\n});\n\nfunction render() {\n view.render({\n fileContainer: host,\n oldFile,\n newFile,\n lineAnnotations: annotations,\n });\n}\n\nrender();\n\nconst editor = new Editor<'file-diff', ThreadMetadata>(\n 'file-diff',\n {},\n 'src/value.ts:draft'\n);\nlet finishEditing: (() => void) | undefined = editor.edit(view);\n\nexport function stopEditing() {\n const finish = finishEditing;\n finishEditing = undefined;\n finish?.();\n}\n\nexport function removeSurface() {\n stopEditing();\n view.cleanUp();\n}\n```\n\n`onEditChange` receives one `EditorChangeEvent`. Observe its remapped\n`lineAnnotations`, but do not feed them back into the surface during the active\nsession. Store the final collection from `onEditComplete` alongside the accepted\nfile or diff. Use stable metadata IDs for application state that belongs to an\nannotation.\n\nPass a third `editStateKey` argument to `new Editor` when a later editor\ninstance should resume/save the in-memory draft, undo/redo history, selections,\nand editor-owned view state.\n\nUse `VirtualizedFile` or `VirtualizedFileDiff` with a `Virtualizer` for a large\nstandalone surface. Load `@pierre/diffs/edit` with `import()` when edit mode is\noptional and the initial bundle must omit the editor.\n\n## Edit `CodeView` items\n\nPass a factory through `CodeViewOptions.createEditor`:\n\n```ts\nimport { CodeView } from '@pierre/diffs';\nimport { Editor } from '@pierre/diffs/edit';\n\nexport function mountEditableCodeView(root: HTMLElement) {\n const viewer = new CodeView({\n getEditStateKey(item) {\n return 'draft:' + item.id;\n },\n createEditor(editorType, options, editStateKey) {\n return new Editor(editorType, options, editStateKey);\n },\n onItemEditChange(event, item) {\n saveItemDraft(item.id, event.file, event.lineAnnotations);\n },\n onItemEditComplete(event, item, nextItem) {\n if (item.type !== 'file' || !('file' in event)) return 'reject';\n\n // Re-key only if this item participates in keyed render caching.\n event.file.cacheKey = item.id + ':v' + nextItem.version;\n return 'accept';\n },\n });\n\n viewer.setup(root);\n viewer.setItems([\n {\n id: 'file:src/value.ts',\n type: 'file',\n file: {\n name: 'src/value.ts',\n contents: 'export const value = 1;',\n },\n edit: true,\n version: 0,\n },\n ]);\n\n return viewer;\n}\n```\n\nSet `edit: true` on an item and increment its `version`. `onItemEditChange`\nreceives `(event, item)`; use `event.file` and `event.lineAnnotations` without\nfeeding the change back into the viewer. Completion receives\n`(event, item, nextItem)` whenever a session ends, including when its final text\nis unchanged. `CodeView` builds `nextItem` with the final contents and\nannotations, `edit: false`, and an incremented `version`. If you use keyed\nrender caching, assign a fresh `cacheKey` to `event.file` or `event.fileDiff`.\nReturn `'accept'` to install `nextItem` while the item remains present or\n`'reject'` to restore the original item while it remains present. During removal\nor viewer teardown, neither decision reinserts the item. A missing completion\ncallback rejects. A controlled React owner should put `nextItem` into its\n`items` state only when the item should remain.\n\n`getEditStateKey(item)` opts an item into draft, undo/redo, selection, and\neditor-owned view-state retention across editor instances. Forward the resulting\nthird factory argument to `new Editor`. `CodeView` creates and removes the item\neditors.\n\n`viewer.getEditor(id)` returns the current `Editor` instance. Call\n`viewer.cleanUp()` when the host removes the viewer.\n\nWhen a worker pool highlights an editable surface, set\n`useTokenTransformer: true` in the worker `highlighterOptions`.\n\n\n# Recipe: render with React\n\n## Select a surface\n\n| Input or layout | Component |\n| ------------------------------------------- | ---------------- |\n| One `FileContents` object | `File` |\n| Old and new `FileContents` objects | `MultiFileDiff` |\n| Existing `FileDiffMetadata` | `FileDiff` |\n| One unified patch string | `PatchDiff` |\n| One file with merge conflicts | `UnresolvedFile` |\n| One scroll region with many files and diffs | `CodeView` |\n\nUse `MultiFileDiff` when the app has old and new file contents:\n\n```tsx\nimport { MultiFileDiff } from '@pierre/diffs/react';\n\n;\n```\n\nPass source data, annotations, and slot renderers as component props. Pass\ndisplay, theme, interaction, and highlighting settings through `options`.\n\nKeep file objects and option objects stable when their values do not change.\nWrap a large standalone surface in `Virtualizer`. Use `CodeView` when one scroll\nregion contains a list of files or diffs.\n\nUse the matching preload function from `@pierre/diffs/ssr` when the server must\nrender the initial highlighted markup.\n\n\n# Recipe: preload a diff on the server\n\nCreate props on the server and pass the result to the matching React component:\n\n```tsx\nimport { preloadMultiFileDiff } from '@pierre/diffs/ssr';\nimport { MultiFileDiff } from '@pierre/diffs/react';\n\nconst preloaded = await preloadMultiFileDiff({\n oldFile: { name: 'src/value.ts', contents: oldSource },\n newFile: { name: 'src/value.ts', contents: newSource },\n options: { theme: 'pierre-dark', diffStyle: 'split' },\n});\n\n;\n```\n\nSelect the preload function that matches the client component. Use\n`preloadDiffHTML` or `preloadUnresolvedFileHTML` when the host needs an HTML\nstring only.\n\n\n# Recipe: render with vanilla JavaScript\n\n## Select a surface\n\n| Input or layout | Class |\n| ------------------------------------------- | --------------------- |\n| One `FileContents` object | `File` |\n| Existing or parsed `FileDiffMetadata` | `FileDiff` |\n| One file with merge conflicts | `UnresolvedFile` |\n| One large file | `VirtualizedFile` |\n| One large diff | `VirtualizedFileDiff` |\n| One scroll region with many files and diffs | `CodeView` |\n\nParse the files, create the view, and render it into a host:\n\n```ts\nimport { FileDiff, parseDiffFromFile } from '@pierre/diffs';\n\nconst host = document.querySelector('#diff');\nif (host == null) throw new Error('Missing diff host');\n\nconst fileDiff = parseDiffFromFile(\n { name: 'src/value.ts', contents: oldSource },\n { name: 'src/value.ts', contents: newSource }\n);\n\nconst view = new FileDiff({\n diffStyle: 'split',\n theme: 'pierre-dark',\n});\n\nview.render({ fileContainer: host, fileDiff });\n```\n\nKeep the class instance while the host remains mounted. Call `render` again when\nthe source data changes. Call `setOptions`, `setThemeType`,\n`setLineAnnotations`, or `setSelectedLines` for targeted updates.\n\nUse a `Virtualizer` with `VirtualizedFile` or `VirtualizedFileDiff` for one\nlarge surface. Use `CodeView` for a list that shares one scroll region. Call\n`cleanUp()` when the host removes the surface.\n\n\n# Recipe: use a worker pool\n\nWrap React diff surfaces in one provider:\n\n```tsx\nimport { WorkerPoolContextProvider } from '@pierre/diffs/react';\n\n\n new Worker(new URL('@pierre/diffs/worker/worker.js', import.meta.url), {\n type: 'module',\n }),\n }}\n highlighterOptions={{\n langs: ['typescript', 'tsx'],\n theme: { light: 'pierre-light', dark: 'pierre-dark' },\n }}\n>\n {children}\n;\n```\n\nFor vanilla JavaScript, call `getOrCreateWorkerPoolSingleton` and pass the\nresult as the second constructor argument to a render class. Call\n`terminateWorkerPoolSingleton()` when the application tears down the shared\npool.\n\n\n---\nname: diffs\ndescription:\n Use when an app uses @pierre/diffs to render or edit code files, diffs,\n patches, merge conflicts, or CodeView review surfaces, including React,\n vanilla JavaScript, SSR, workers, annotations, selection, and custom syntax\n languages or themes.\n---\n\n# `@pierre/diffs`\n\nUse `@pierre/diffs` to render syntax-highlighted files and diffs. Use its\noptional editor, SSR, and worker entries for those capabilities.\n\nFor standalone HTML or token generation with `@pierre/highlights`, read the\n[highlights skill](../highlights/SKILL.md).\n\n## Install\n\n```bash\npnpm add @pierre/diffs\n```\n\nInstall `react` and `react-dom` when the app uses the React entry.\n\n## Select an API reference\n\n| Surface | Reference |\n| ------------------------------------------------------------ | ------------------------------------------------------ |\n| Root components, parsing, and file extension APIs | [Core API](references/api-core.md) |\n| Languages, themes, highlighter state, and streams | [Highlighting API](references/api-highlighting.md) |\n| Renderers, managers, DOM helpers, comparisons, and constants | [Low-level rendering API](references/api-rendering.md) |\n| Shared data, option, render, selection, and editor types | [Shared types](references/api-types.md) |\n| `@pierre/diffs/react` | [React API](references/api-react.md) |\n| `@pierre/diffs/edit` | [Editor API](references/api-editor.md) |\n| `@pierre/diffs/ssr` | [SSR API](references/api-ssr.md) |\n| `@pierre/diffs/worker` and worker scripts | [Worker API](references/api-worker.md) |\n\n## Select a recipe\n\n| Task | Recipe |\n| ----------------------------------- | ------------------------------------------------------------------------ |\n| Render a file or diff in React | [Render with React](references/recipe-react.md) |\n| Render a file or diff without React | [Render with vanilla JavaScript](references/recipe-vanilla.md) |\n| Build a virtualized review surface | [Use CodeView](references/recipe-code-view.md) |\n| Edit a React surface or CodeView | [Edit with React](references/recipe-edit-react.md) |\n| Edit a vanilla surface or CodeView | [Edit with vanilla JavaScript](references/recipe-edit-vanilla.md) |\n| Preload markup on the server | [Use SSR](references/recipe-ssr.md) |\n| Highlight through a worker pool | [Use workers](references/recipe-workers.md) |\n| Add line annotations and selection | [Add annotations and selection](references/recipe-annotations.md) |\n| Register a custom language or theme | [Register custom highlighting](references/recipe-custom-highlighting.md) |\n\n\n# Incremental editing\n\n`LiveTokenizer` owns a document and an isolated WebAssembly instance. It\nre-tokenizes changed lines and following lines until the lexer state converges\nwith the retained state. Constructor options extend the\n[tokenization options](rendering.md#options-and-languages) with `code` (default\nempty), `renderRange`, and `onDeferTokenize`.\n\n## Apply edits\n\n```ts\nimport { LiveTokenizer } from '@pierre/highlights';\nimport { pierreDark } from '@pierre/highlights/themes';\n\nconst live = new LiveTokenizer({\n code: 'const answer = 41;\\nconsole.log(answer);',\n lang: 'ts',\n theme: pierreDark,\n});\n\ntry {\n const update = live.applyEdits([\n {\n range: {\n start: { line: 0, character: 15 },\n end: { line: 0, character: 17 },\n },\n newText: '42',\n },\n ]);\n\n console.log(live.getLineText(0)); // const answer = 42;\n for (const change of update.lineChanges) {\n for (let line = change.newStartLine; line < change.newEndLine; line++) {\n console.log(line, live.getLineTokens(line));\n }\n }\n} finally {\n live.dispose();\n}\n```\n\nEvery edit range uses zero-based lines and UTF-16 character positions in the\ndocument before the batch. The end position is exclusive. Overlapping ranges are\nrejected before mutation. `reset(code, options?)` replaces the whole text while\nretaining language and theme options; recreate the tokenizer to change those\noptions.\n\nWithout `renderRange`, updates finish synchronously and `update.lines` is empty.\nUse `lineChanges` and `getLineTokens()` to refresh a renderer. Each\n`LiveLineChange` maps `[oldStartLine, oldEndLine)` to\n`[newStartLine, newEndLine)`; also remove deleted rows when reconciling a view.\n`LiveTokenizerUpdate` includes `revision`, `previousLineCount`, and `lineCount`.\n\n`getLineTokens(line)` returns `{ tokens, bracketIgnoredRanges }`. Its token\noffsets are relative to that line. `bracketIgnoredRanges` contains end-exclusive\nUTF-16 column pairs for strings, comments, and regexes that bracket matching\nshould skip.\n\n## Prioritize a viewport\n\n`renderRange: [startLine, endLine]` uses post-edit line numbers and excludes\n`endLine`. Pass it on each update that should prioritize a viewport. Dirty lines\nbefore the viewport must also be processed to establish lexer state; the\nremaining work runs in background slices.\n\n```ts\nimport { LiveTokenizer } from '@pierre/highlights';\nimport { pierreDark } from '@pierre/highlights/themes';\n\nconst live = new LiveTokenizer({\n code: 'const answer = 41;\\nconsole.log(answer);',\n lang: 'ts',\n theme: pierreDark,\n renderRange: [0, 1],\n onDeferTokenize(lines) {\n // This callback can run before the constructor returns.\n for (const [line, tokens] of lines) console.log(line, tokens);\n },\n});\n\ntry {\n console.log(live.getLineTokens(0)); // Read the initial viewport after construction.\n const update = live.applyEdits(\n [\n {\n range: {\n start: { line: 0, character: 15 },\n end: { line: 0, character: 17 },\n },\n newText: '42',\n },\n ],\n { renderRange: [0, 1] }\n );\n for (const [line, tokens] of update.lines) console.log(line, tokens);\n\n live.flush(); // Finish pending work before reading the complete document's tokens.\n} finally {\n live.dispose();\n}\n```\n\n`update.lines` contains re-tokenized lines inside the range, not the entire\nviewport. Finished lines outside it arrive through `onDeferTokenize`, which can\nrun synchronously during construction or an update. Keep the callback\nindependent of the variable receiving the new instance. Schedule further edits\nafter the current update; calling `applyEdits()` or `reset()` inside its\nsynchronous callback throws.\n\nBoth maps contain `HighlightedToken[]`: tuples of\n`[character, foregroundColor, text]` using the first resolved theme. Read\n`getLineTokens()` when font styles or multi-theme `htmlStyle` maps are needed.\nWhile `pendingTokenization` is true, unreached lines can retain old tokens and\nnew lines can have foreground-only tokens. Call `flush()` before reads that\nrequire fully current tokens.\n\n## Document and lifecycle API\n\n| Member | Purpose |\n| ---------------------------------------------- | ---------------------------------------------------------------------------- |\n| `revision`, `lineCount`, `pendingTokenization` | Read document revision, line count, and pending work |\n| `applyEdits(edits, options?)` | Apply a batch and return `LiveTokenizerUpdate` |\n| `reset(code, options?)` | Replace text and return `LiveTokenizerUpdate` |\n| `getLineLength(line)`, `getLineText(line)` | Read UTF-16 length or text excluding the terminator |\n| `getText()` | Read all text, preserving LF, CRLF, and lone CR |\n| `getLineTokens(line)` | Read themed tokens and bracket-ignored ranges |\n| `getLineRecords(line)` | Read packed raw token records |\n| `flush(endLine?)` | Finish pending work before an exclusive line bound, or all work when omitted |\n| `pause()`, `resume()` | Suspend or resume background tokenization |\n| `dispose()` | Release the instance and cancel deferred work; safe to repeat |\n\n`flush()`, `reset()`, and `applyEdits()` (even a no-op batch) resume paused\nwork. After disposal, other methods and state getters throw. Keep one tokenizer\nfor the document's lifetime and dispose it when the editor unmounts or closes.\n\n## Packed records\n\n`getLineRecords()` returns `LiveTokenRecords` with `revision`, `format`, and\n`data: Uint32Array`. Starts are implicit: zero for the first token, then the\nprevious token's end. End positions are UTF-16 columns within the line.\n\n| Format | Encoding |\n| ---------- | -------------------------------------------------------------------- |\n| `packed24` | One word per token: `tokenId = word >>> 24`, `end = word & 0xffffff` |\n| `wide32` | Pairs of `[endUtf16, tokenId]` for lines exceeding the 24-bit range |\n\nImport `tokenNames` from `@pierre/highlights` to map IDs to syntax scope names.\nViews are invalidated by successful edits, resets, deferred tokenization slices,\nand disposal. Copy `records.data.slice()` before retaining data across those\noperations. Deferred work can invalidate data without changing the document\nrevision.\n\nThe root entry exports `HighlightedToken`, `LiveLineChange`, `LivePosition`,\n`LiveTextEdit`, `LiveTokenizerOptions`, `LiveTokenizerUpdate`,\n`LiveTokenRecords`, and `LiveUpdateOptions`. Use `LivePosition` and\n`LiveTextEdit` for the public position and edit types.\n\n\n# Rendering\n\n## HTML\n\n```ts\nimport { codeToHtml } from '@pierre/highlights';\nimport { pierreDark } from '@pierre/highlights/themes';\n\nconst html = new TextDecoder().decode(\n codeToHtml('const answer = 42;', { lang: 'ts', theme: pierreDark })\n);\n```\n\n`codeToHtml()` returns UTF-8 bytes for a\n`
…
` fragment. Source text is\nHTML-escaped and theme styles are applied inline. Decode the bytes immediately,\nor call `.slice()` before retaining them across another highlighting or\ntokenization call on the same highlighter. The top-level `codeToHtml()` and\n`codeToTokens()` share one instance.\n\n## Tokens\n\n```ts\nimport { codeToTokens } from '@pierre/highlights';\nimport { pierreDark } from '@pierre/highlights/themes';\n\nconst result = codeToTokens('const answer = 42;\\n', {\n lang: 'ts',\n theme: pierreDark,\n});\n\nconsole.log(result.tokens[0]); // ThemedToken[] for the first line\nconsole.log(result.fg, result.bg); // Root foreground and background colors\n```\n\n`TokensResult.tokens` contains one `ThemedToken[]` per line. Line terminators\nare excluded from content; a trailing line break adds an empty final line.\nOffsets count UTF-16 code units from the start of the complete input.\n\n| Token field | Meaning |\n| ---------------------- | ----------------------------------------------------------------------------- |\n| `content`, `offset` | Text and its absolute UTF-16 start index |\n| `color`, `fontStyle` | Single-theme color and Shiki-style font flags |\n| `htmlStyle` | Multi-theme styles, including custom properties; apply the whole map |\n| `type` | `1` comment, `2` string, `3` regex, otherwise `0` or omitted |\n| `bgColor`, `htmlAttrs` | Optional background and span attributes for renderer/transformer integrations |\n\nHighlights emits italic (`1`) and bold (`2`) font flags. The type also supports\nunderline (`4`) and strikethrough (`8`) supplied by transformers. Use text nodes\nor escape `content` in a custom HTML renderer. Apply root colors as well as\ntoken styles. Token objects are Shiki-compatible; lexer boundaries and syntax\nclassifications can differ.\n\nWith multiple themes, `fg` and `bg` can contain CSS declaration lists, and\n`defaultColor: false` supplies `rootStyle`. See [Themes](themes.md) for\nrendering those styles. Equal runs can share an `htmlStyle` object; replace that\nobject when customizing one token.\n\n## Options and languages\n\nBoth functions accept `string`, `Uint8Array`, or `ArrayBuffer` input; bytes are\nUTF-8. Supply `lang` and exactly one of `theme` or `themes`.\n\n| Option | Meaning |\n| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- |\n| `lang` | Built-in language name or alias, typed as `Lang` |\n| `theme` | One Zed `Theme` or `ThemeFamily` object |\n| `themes` | Non-empty map of named theme objects; see [Themes](themes.md) |\n| `cssVariablePrefix` | Prefix for CSS-variable colors and theme properties; default `--hls-` |\n| `defaultColor` | With `themes`, inline theme key (default `light`), `false`, or `'light-dark()'` |\n| `tokenizeMaxLineLength` | Tokenization only: lines at or above this UTF-16 length become one token without syntax styling; `0` or omission disables it |\n\nThe line-length limit reduces token objects, while the lexer still processes the\nline to preserve subsequent state. It also applies to streaming and live\ntokenization, but is not an HTML option.\n\nLanguage names and aliases are case-insensitive. Unknown names throw\n`RangeError`. Highlights performs no automatic language detection or filename\nresolution. Validate external labels and choose an explicit fallback:\n\n```ts\nimport { isSupportedLanguage } from '@pierre/highlights';\n\nconst requestedLanguage: string = 'typescript';\nconst lang = isSupportedLanguage(requestedLanguage)\n ? requestedLanguage\n : 'plain';\n```\n\n`isSupportedLanguage()` narrows a string to `Lang`. Plain text aliases include\n`plain`, `text`, `plaintext`, and `txt`. Lexers are built in; custom TextMate\ngrammar registration belongs to the Shiki APIs in `@pierre/diffs`.\n\n## Runtime and types\n\n`createHighlighter()` returns an isolated `Highlighter` using the initialized\nmodule. Embedders can pass their own compiled `WebAssembly.Module` to\n`createHighlighter(module)` or replace the shared highlighter with\n`init(module)`. Both functions are synchronous. `Highlighter` exposes\n`codeToHtml()` and `codeToTokens()` with the signatures above. Import the normal\npackage entry for automatic initialization.\n\nCore public types are `Highlighter`, `Lang`, `CodeToHtmlBaseOptions`,\n`CodeToHtmlOptions`, `CodeToTokensBaseOptions`, `CodeToTokensOptions`,\n`ThemeOptions`, `ThemedToken`, and `TokensResult`. Theme types are covered in\n[Themes](themes.md); live types and `tokenNames` in\n[Incremental editing](live.md).\n\n\n# Streaming\n\n`StreamTokenizer` extends `TransformStream`. It takes\nthe [tokenization options](rendering.md#options-and-languages) and owns an\nisolated WebAssembly instance. Use it for append-only input; use\n[LiveTokenizer](live.md) when previously received text can change.\n\n## Pipe a readable stream\n\nPass a UTF-8 byte stream through the tokenizer with `pipeThrough()`. It decodes\nbytes internally, including characters split across chunks. Given an existing\n`ReadableStream` named `responseBody`:\n\n```ts\nimport { StreamTokenizer } from '@pierre/highlights';\nimport { pierreDark } from '@pierre/highlights/themes';\n\nconst lines = responseBody.pipeThrough(\n new StreamTokenizer({ lang: 'ts', theme: pierreDark })\n);\n\nfor await (const tokens of lines) {\n console.log(tokens); // One ThemedToken[] per line\n}\n```\n\nClosing the writable side emits the remaining lines and releases the instance.\nCancellation or abort discards buffered input and releases it. Let the stream\npipeline manage completion; use the synchronous methods below when manually\nfeeding strings or UTF-8 bytes.\n\n## Push chunks synchronously\n\n```ts\nimport { StreamTokenizer } from '@pierre/highlights';\nimport { pierreDark } from '@pierre/highlights/themes';\n\nconst stream = new StreamTokenizer({ lang: 'ts', theme: pierreDark });\n\ntry {\n console.log(stream.pushCode('const answer =')); // []: incomplete line\n const bytes = new TextEncoder().encode(' 42;\\nconsole.log(answer);');\n console.log(stream.pushCode(bytes)); // First line\n console.log(stream.end()); // Remaining line; also disposes the instance\n} finally {\n stream.dispose();\n}\n```\n\n| Method | Behavior |\n| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |\n| `pushCode(chunk: string \\| Uint8Array)` | Accepts text or UTF-8 bytes; returns `ThemedToken[][]` for completed lines and buffers the unfinished line |\n| `end()` | Finishes decoding and returns remaining lines, including an empty final line after a trailing terminator, then disposes |\n| `dispose()` | Discards buffered input and releases the instance; safe to repeat |\n\nChunks can produce zero or more lines. Lines are emitted when `\\n` arrives,\nincluding in CRLF input, or at `end()`. Lexer state is retained across chunks.\nToken offsets are UTF-16 indices from the start of the complete stream. Apply\nthe same token styles described in [Rendering](rendering.md#tokens).\n\nCall `end()` once when input finishes. Calling `pushCode()` or `end()` after\ndisposal throws. Keep `dispose()` in cleanup paths for cancellation and errors.\n\nUTF-8 characters can span consecutive byte chunks. Mixing strings and bytes\npreserves chunk order: a nonempty string flushes incomplete UTF-8 as a\nreplacement character before appending the string. Empty chunks leave buffered\ninput intact.\n\n\n# Themes\n\nHighlights takes Zed-compatible theme objects. Load them from\n`@pierre/highlights/themes`; `@pierre/theme` supplies Shiki and VS Code objects\nwith a different shape.\n\n## Load a theme\n\n```ts\nimport { pierreDark } from '@pierre/highlights/themes';\nimport vitesseDark from '@pierre/highlights/themes/vitesse-dark';\nimport { themes } from '@pierre/highlights/themes/loader';\n\nconst { default: lazyTheme } = await themes['pierre-dark']();\n```\n\n| Entry | Exports |\n| ---------------------------------- | -------------------------------------------------------- |\n| `@pierre/highlights/themes` | Camel-case named themes, `cssVariables`, and `toCSS()` |\n| `@pierre/highlights/themes/` | One theme as the default export, e.g. `pierre-dark` |\n| `@pierre/highlights/themes/loader` | `themes`, a map from bundled IDs to async module loaders |\n\nPass the resolved object as `theme`; a string ID is not accepted. A\n`ThemeFamily` resolves to its first member. Pass `family.themes[index]` to\nselect another. Theme preparation is cached by object identity; create new\nobjects when changing values.\n\nFor `@pierre/diffs` components, load these objects through\n`registerCustomTheme(name, loader, 'zed')` and select\n`preferredHighlighter: 'highlights'`. See the\n[custom highlighting recipe](../../diffs/references/recipe-custom-highlighting.md)\nfor registration and backend selection.\n\n## Custom themes\n\n```ts\nimport type { Theme } from '@pierre/highlights';\n\nconst theme = {\n name: 'App Dark',\n appearance: 'dark',\n style: {\n 'editor.background': '#101010',\n 'editor.foreground': '#eeeeee',\n syntax: {\n keyword: { color: '#c084fc', font_weight: 700 },\n comment: { color: '#888888', font_style: 'italic' },\n },\n },\n} satisfies Theme;\n```\n\nColors support three-, four-, six-, and eight-digit hex and numeric\n`color(display-p3 ...)` values. Use the CSS-variable mode below for application\nvariables. Syntax scopes such as `keyword.control` inherit from their nearest\nconfigured parent.\n\nTheme types come from `@pierre/highlights`:\n\n| Type | Shape |\n| --------------------- | -------------------------------------------------------------------- |\n| `Theme` | `name`, `appearance`, `style`, and optional `cssVariables: true` |\n| `ThemeFamily` | `themes: readonly Theme[]`, optional `name` and `author` |\n| `ThemeStyle` | Editor colors and `syntax`, plus additional Zed style keys |\n| `ThemeSyntaxSettings` | Optional `color`, `font_style`, and `font_weight` |\n| `ThemePlayer` | Optional collaborator `cursor`, `selection`, and `background` colors |\n| `ThemeOptions` | Exactly one of `theme` or `themes` |\n\nEach `style.syntax` value can be a color string or `ThemeSyntaxSettings`.\n\n## Switch colors with CSS variables\n\n```ts\nimport { codeToHtml } from '@pierre/highlights';\nimport { cssVariables, pierreDark, toCSS } from '@pierre/highlights/themes';\n\nconst cssVariablePrefix = '--code-';\nconst html = new TextDecoder().decode(\n codeToHtml('const answer = 42;', {\n lang: 'ts',\n theme: cssVariables,\n cssVariablePrefix,\n })\n);\nconst stylesheet = `.highlights { ${toCSS(pierreDark, { cssVariablePrefix })} }`;\n```\n\nInclude the stylesheet with the markup. `toCSS(theme, options?)` accepts a\n`Theme` and returns declarations without a selector. Apply them to the code\nblock or an ancestor. Keep its prefix and the highlighting prefix equal; both\ndefault to `--hls-`. Changing declarations updates colors without tokenization.\nThis mode controls colors only and ignores theme font style and weight.\n\n## Multiple themes\n\nAll highlighting and tokenization APIs accept a `themes` map. `defaultColor`\nselects how it renders:\n\n| Value | Result |\n| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- |\n| A theme key | Applies that scheme inline and emits other schemes as custom properties; defaults to `light` and throws if the key is absent |\n| `false` | Emits all schemes as custom properties for CSS to select |\n| `'light-dark()'` | Requires `light` and `dark`; merges colors into CSS `light-dark()` values following the page's `color-scheme` |\n\n```ts\nimport { codeToHtml } from '@pierre/highlights';\nimport { pierreDark, pierreLight } from '@pierre/highlights/themes';\n\nconst html = new TextDecoder().decode(\n codeToHtml('const answer = 42;', {\n lang: 'ts',\n themes: { light: pierreLight, dark: pierreDark },\n defaultColor: false,\n })\n);\n```\n\nInclude CSS to select the emitted properties:\n\n```css\n.highlights {\n color: var(--hls-light);\n background-color: var(--hls-light-bg);\n}\n\n.highlights span {\n color: var(--hls-light);\n font-style: var(--hls-light-font-style, normal);\n font-weight: var(--hls-light-font-weight, normal);\n}\n\n@media (prefers-color-scheme: dark) {\n .highlights {\n color: var(--hls-dark);\n background-color: var(--hls-dark-bg);\n }\n\n .highlights span {\n color: var(--hls-dark);\n font-style: var(--hls-dark-font-style, normal);\n font-weight: var(--hls-dark-font-weight, normal);\n }\n}\n```\n\nFor a custom token renderer, apply each token's complete `htmlStyle` map to its\nspan. With `defaultColor: false`, apply `result.rootStyle` as the container's\ninline style, then use equivalent CSS for that container. With an inline\ndefault, the root style is `background-color:${result.bg};color:${result.fg}`;\nthese fields can include additional declarations. Preserve those declarations\ninstead of treating them as single CSS color values.\n\n## Named CSS palettes\n\nA theme can use `cssVariables: { prefix, defaults }` to map syntax categories to\napplication palette variables while retaining font settings:\n\n```ts\nconst theme = {\n name: 'App palette',\n appearance: 'dark',\n cssVariables: {\n prefix: '--app-',\n defaults: { keyword: '#c084fc' },\n },\n style: {\n syntax: {\n keyword: { color: 'keyword', font_weight: 700 },\n comment: { color: 'muted', font_style: 'italic' },\n },\n },\n} satisfies Theme;\n```\n\nSyntax `color` values are variable suffixes in this mode. Unconfigured syntax\ncategories inherit the `foreground` variable, and defaults become CSS `var()`\nfallbacks. The palette prefix belongs to the theme and is independent of the\nprefix used for multiple theme output. Diffs uses this mode for its portable\n`createCSSVariablesTheme` palette.\n\n\n---\nname: highlights\ndescription:\n Use when an app uses @pierre/highlights to generate syntax-highlighted HTML or\n tokens, stream code, incrementally tokenize edits, or apply Zed-compatible\n themes and CSS variables.\n---\n\n# `@pierre/highlights`\n\nUse `@pierre/highlights` for standalone syntax highlighting with built-in\nWebAssembly lexers. Choose HTML for a complete code block, tokens for a custom\nrenderer, `StreamTokenizer` for append-only input, or `LiveTokenizer` for an\neditable document.\n\n## Install\n\n```bash\npnpm add @pierre/highlights\n```\n\nImport from `@pierre/highlights`. Conditional exports initialize WebAssembly\nautomatically for Node.js, browsers, and Cloudflare Workers. Highlighting is\nsynchronous after import; ordinary usage needs no `init()` or language\nregistration.\n\n## Select a reference\n\n| Task | Reference |\n| -------------------------------------------------------------------------- | ----------------------------------------- |\n| Generate HTML or tokens, validate a language, or manage a Wasm module | [Rendering](references/rendering.md) |\n| Load or customize themes, switch CSS variables, or render multiple schemes | [Themes](references/themes.md) |\n| Tokenize streamed strings or bytes | [Streaming](references/streaming.md) |\n| Apply edits, prioritize a viewport, or read packed token records | [Incremental editing](references/live.md) |\n\nFor file, diff, or editor components, read the [diffs skill](../diffs/SKILL.md).\n\n\n"}