AGENTS.md

Project Scope

This repository contains vue3-ts-jsoneditor, a Vue 3 wrapper/plugin around vanilla-jsoneditor. Primary goals when changing code:

• keep the public component API stable unless the task explicitly changes it;
• preserve SSR-safe behavior and lazy loading behavior;
• keep the package buildable as a published library, not just as a demo app.

Stack

• Vue 3
• TypeScript
• Vite 7
• Vitest 4
• ESLint 9
• pnpm workspace with a single package

Node requirement from package.json: >=20.19.0.

Repository Map

• src/components/JsonEditor.vue: main wrapper component and the highest-risk file for behavior changes.
• src/JsonEditorPlugin.ts: plugin install entry and exported library surface.
• src/components/utils.ts: content/model conversion helpers.
• src/components/styles-handler.ts: runtime style injection helpers.
• src/components/full-width-button-handler.ts: fullscreen button behavior.
• src/components/string-styles.ts: CSS string assets injected at runtime.
• src/components/index.ts: component export barrel.
• src/types.ts: shared public types.
• tests/unit/*.spec.ts: unit coverage for component behavior, plugin install, utils, and handlers.
• README.md: public usage documentation and API notes.

Source Of Truth

• Treat src/** and tests/** as editable source.
• Treat dist/, coverage/, gh-dist/, node_modules/, tsconfig.tsbuildinfo, and *.tgz artifacts as generated output. Do not hand-edit them unless the user explicitly asks.
• If a change affects public props, events, plugin options, or install behavior, update README.md.
• For third-party library/framework APIs, prefer MCP Context7 first. If exact API behavior is uncertain and Context7 is unavailable, do not guess.

Working Rules

• Prefer minimal, API-safe changes. This package is a published library, so regressions in emitted events, v-model behavior, SSR, or plugin registration are high impact.
• Preserve current naming and export compatibility:
  • default component export;
  • named JsonEditorPlugin export;
  • generated type declarations from the library build.
• Keep browser-only logic guarded so SSR consumers do not break.
• Preserve behavior across supported modes: tree, text, and table.
• When changing DOM helpers or style injection, check for duplicate insertion, cleanup behavior, and test isolation.
• When changing model synchronization, validate both modelValue and explicit json / text bindings.

Commands

Prefer pnpm in this repo.

• Install deps: pnpm install
• Dev server: pnpm dev
• Lint: pnpm lint
• Auto-fix lint: pnpm lint:fix
• Type check: pnpm type-check
• Unit tests: pnpm test
• Coverage: pnpm test:coverage
• Build library: pnpm build
• Pack publishable tarball: pnpm pack
• Package + browser smoke: pnpm smoke
• Package install/build smoke only: pnpm smoke:consumer

Validation Expectations

• For code changes, run pnpm lint, pnpm test, and pnpm type-check when relevant.
• For public API or packaging changes, also run pnpm build.
• If you cannot run a validation step, say so explicitly in the handoff.

Testing Guidance

• Add or update unit tests in tests/unit/ for any behavior change.
• Favor targeted tests around:
  • emitted events;
  • v-model sync behavior;
  • plugin installation;
  • fullscreen/style helper side effects;
  • SSR-sensitive guards.

Release Notes

• Releases are handled through semantic-release.
• Branch strategy is main-only:
  • branch new feat/*, fix/*, and chore/* work from main
  • open pull requests into main
  • treat main as the only release branch
  • do not rely on a long-lived develop branch for unreleased work
• Release intent rules:
  • feat -> minor
  • fix and perf -> patch
  • docs -> patch
  • ci, build, style, test, chore, and refactor should not trigger a release
• Commit messages should remain compatible with Conventional Commits.
• Do not manually edit release artifacts unless the task is specifically about release automation.