AGENTS.md

Agent & Assistant Guidelines (PayPal Messaging Components)

Persona & style

• Address the user as Developer.
• Begin only the first assistant response in a new conversation with: "Hi Developer — ."
• Do not repeat this greeting in later responses within the same conversation.
• Telegraph; noun phrases OK; minimal tokens; expand only for clarity.
• Ask clarifying questions whenever requirements are underspecified or constraints are missing.
• For PR comment review tasks: validate each PR comment to ensure it makes sense, avoid false positives, and state why it is valid or not.
• During plan/research: actively look for codebase improvements and friction/misalignment with existing patterns; call them out with concrete suggestions (and tradeoffs when relevant).
• Optimize for correctness + leverage; be direct/critical when needed.
• Never claim checks ran unless they actually ran; cite commands executed.
• Every time you plan a feature, make it comprehensive and detailed, and include robust acceptance criteria to validate the changes. Do not stop until acceptance criteria is met.

Subagents

• Always wait for all subagents to complete before yielding.
• Spawn subagents automatically when:
  • Parallelizable work (e.g., npm run lint + npm test, snapshot review + content scan).
  • Long-running or blocked tasks where a worker can run independently (e.g., functional suites, build validation).
  • Isolation for risky changes or checks (e.g., content/i18n, modal rendering, build/release scripts).
• Give each subagent crisp context, the exact files it needs, and clear instructions with expected output format.
• When a subagent completes, log the finish here, mark the task done, then immediately check for newly unblocked tasks.
• Repeat the cycle until the entire plan is complete.
• Use subagents liberally to keep the main context window clean for long-running work.
• Offload research, exploration, and parallel analysis to subagents whenever tasks are independent.
• Keep one task per subagent for focused execution and easier validation handoff.

Docs-first (read before coding)

• README.md (scripts, dev server targets, stage env override)
• CONTRIBUTING.md (contribution expectations)
• docs/message-demo-pages.md (demo + snapshot pages)
• docs/message-types.md (message/modal type naming by locale)
• docs/message-stage-bundle.md (internal stage-tag bundle workflow)
• tests/playwright/README.md (Playwright usage notes)
• src/components/modal/v2/parts/views/README.md (how to add modal "views" correctly)

Context7 MCP (3rd-party docs)

• Use Context7 for library/API documentation, setup steps, and configuration guidance.
• Always call resolve-library-id first, then query-docs with that ID.
• Be specific in queries; max 3 calls per question.

Project snapshot

• Runtime: use the Node version in .nvmrc (currently 22); treat .nvmrc as the source of truth
• Build: Webpack 4 + @krakenjs/webpack-config-grumbler (webpack.config.js, webpack.config.dev.js)
• UI: Preact + JSX (preact, @krakenjs/jsx-pragmatic) + SCSS (modal v2)
• Cross-domain components: Zoid + Post-Robot (@krakenjs/zoid, @krakenjs/post-robot)
• Primary outputs:
  • dist/ bundles (built via release/asset script; do not hand-edit)
  • demo/ pages for local verification
• Content: locale-specific JSON under content/ (messages/modals/offers)

Key directories (where things live)

• src/library/: library entrypoints (messaging.js, modal.js)
• src/components/: Zoid components
  • src/components/message/
  • src/components/modal/v2/ (modern modal)
• src/server/: server-side rendering / endpoints used by demos and tests
• content/: localized copy and configuration payloads
  • content/messages/<LOCALE>/*.json
  • content/modals/<LOCALE>/*.json
  • content/offers/<LOCALE>/*.json
• demo/: local demo + snapshot pages (demo/standalone.html, demo/snapshot/*.html)
• tests/: unit + functional snapshot suites + Playwright
• utils/devServerProxy/: local dev-server proxy hooks

Coding & formatting standards

• Prettier: .prettierrc.js (4 spaces, printWidth: 120, single quotes, semicolons)
• ESLint: .eslintrc (Airbnb + Prettier; prettier/prettier enforced as error)
• Lint-staged: .lintstagedrc.js (formats/lints staged JS/JSX + formats json/md/html/css)

Local gate (run before PR / handoff)

• nvm use (uses the version in .nvmrc)
• npm install
• npm run lint
• npm test (unit tests; Jest)

Run additional suites when you touched related areas:

• Functional (puppeteer) tests:
  • Start server: npm run dev:ci
  • Then run:
    • npm run test:func (all functional)
    • npm run test:func:nosnaps (functional without snapshots)
    • npm run test:func:snapshots (v2 snapshot suite)
• Build sanity:
  • npm run build:production (or npm run build:stage / npm run build:sandbox as appropriate)

Verify & iterate (behavior-first)

• If you change rendering/UX, verify with local demo pages:
  • npm start then open demo/standalone.html
  • For multi-banner comparisons: demo/text.html, demo/flex.html (see docs/message-demo-pages.md)
• If you change snapshot-relevant rendering, use snapshot pages (demo/snapshot/*.html) and run the snapshot suite.
• If tests fail: reproduce → fix root cause → re-run the same suite(s) until green.
• When fixing bugs: reproduce first → fix → verify the fix via the most relevant demo/tests.
• Never mark work complete without proving behavior with relevant tests, logs, or runtime checks.
• When relevant, compare behavior between base/main and your changes to confirm intended deltas.
• Apply a staff-level quality bar: ask whether the result is robust, observable, and review-ready.

Tests (what to run and when)

• Unit: npm test (Jest, jsdom; HTML report at tests/__reports__/unit.html)
• Functional / snapshots: Jest + Puppeteer
  • Snapshot update flows:
    • npm run test:func:ciupdate (updates snapshots for functional suite)
    • npm run test:func:snapshots:ciupdate (updates v2 snapshot suite)
  • Targeted snapshots use CONFIG_PATH (from README.md):
    • CONFIG_PATH={locale}/{account} npm run test:func:snapshots -- --testPathPattern {integrationType}
• Playwright: npx playwright test
  • Note: playwright.config.js references ./.github/scripts/runServerV2.sh as webServer.command.
  • If that script is missing in your checkout, Playwright will not be able to auto-start the server; start a dev server yourself (e.g. npm run dev:ci) and adjust the config/command as needed in your change.

Playwright interactive debugging

Use Playwright’s interactive modes when tests fail or when implementing a complex user flow.

• When to use:
  • Browser tests failing; need to see what’s happening.
  • New/complex modal or banner flows; verify end-to-end behavior.
  • Timing/race issues and flaky selectors.
• How to use (CLI) (see tests/playwright/README.md):
  • npx playwright test --ui
  • npx playwright test --debug
  • npx playwright test --headed
  • npx playwright test --project=chromium
  • Tip: cap concurrency locally with --workers <n> if needed.
• Principles:
  • Test what a real user experiences, not what code "should" do.
  • Prefer screenshots/trace on failures; update selectors only after confirming the DOM/state.

Content & i18n safety (JSON under content/)

• Treat content/ as product-facing copy/config; changes are high-impact.
• Keep locale files consistent with existing naming conventions (see docs/message-types.md).
• Prefer minimal diffs; avoid unnecessary reformatting across many JSON files.
• If you update content that affects rendering, run the relevant snapshot suite(s) to catch regressions.

Modal v2 "views" (when adding/changing views)

• Follow src/components/modal/v2/parts/views/README.md:
  • New view folder with Content.jsx
  • Export from the views/index.js
  • Preserve shared structural classNames (content__container, content__body, etc.) to reuse shared styles
  • For per-view overrides, add a local .scss and inject via <style>{fileName._getCss()}</style> pattern

Dev servers & environments

• Primary dev entrypoints:
  • npm run dev (TARGET=sdk)
  • npm run dev:standalone, npm run dev:modal, npm run dev:lander
  • npm run dev:stage, npm run dev:sandbox, npm run dev:production
• Environment override for demos (dev only): set window.__TEST_ENV__ in the demo page (see README.md).

Release & dist hygiene

• Releases are driven by semantic-release (release.config.js) and build assets via ./scripts/semantic-release/assets.sh.
• Avoid committing changes to dist/ unless you are intentionally running the release/asset workflow; dist/ is large and should reflect an intentional build.

Git hooks (Husky) & staged-file hygiene

• Pre-commit runs lint-staged + npm test (see scripts/husky/pre-commit.sh).
• Expect staged JS/JSX to be formatted by Prettier and checked by ESLint before commit (see .lintstagedrc.js).

Cross-platform scripts

• Prefer npm run <script> over ad-hoc command invocations so workflows stay consistent.
• Avoid adding Unix-only shell one-liners directly into package.json scripts; prefer Node scripts or existing repo patterns (e.g. webpack --env ... flags).
• Do not add new dependencies (like cross-env) without approval.

Production safety

• Assume production impact unless stated otherwise; this repo ships merchant-facing messaging UX.
• Prefer small, reversible changes; call out risk when touching content, rendering, tests, or build/release scripts.

Critical thinking

• Fix root cause; avoid band-aids.
• Unsure: read more code/docs; if still ambiguous, ask with short options.
• Conflicts between docs and code: call out; pick the safer/more consistent path.
• Unrecognized large diffs: assume other agent or context missing; proceed cautiously.

SCM & safety

• No destructive git commands (reset --hard, clean) without explicit permission.
• No new deps/services without approval.
• Keep secrets out of code/logs. Use env/global overrides as documented.
• Prefer small, reversible changes; call out risk when touching content rendering, tests, or build/release scripts.

Acceptance criteria (for changes you make)

• Include a clear plan with acceptance criteria before implementing non-trivial changes.
• Keep changes aligned with repo patterns (webpack targets, demo verification, test suites).
• Run the most relevant local gates for the impacted area(s) and cite the commands you executed.

Pull request evidence

• Before publishing a public PR, scan its title, body, branch, commits, screenshots, and testing instructions for internal URLs, stage tags, identifiers, service details, credentials, and merchant or customer data. Replace them with public local-demo instructions.
• Include screenshots or video for visible UI changes. For semantics-only changes, write N/A and include the exact DOM, accessibility-tree, or automated assertion that proves the behavior.
• Bug-fix testing instructions must name the regression covered and the exact command that passes with the fix.
• After opening the PR, verify the live title, body, base branch, diff, labels, and checks.
• For fork PRs, report missing review labels and action_required workflows as maintainer actions. Do not describe missing or unapproved checks as passing.

Plan Mode Default

• Enter plan mode for any non-trivial task (3+ steps or architectural decisions).
• If execution goes sideways, stop and re-plan immediately before continuing.
• Include verification steps in the plan, not only implementation steps.
• Write detailed specs up front to reduce ambiguity and rework.

Demand Elegance (Balanced)

• For non-trivial changes, pause and ask whether there is a more elegant path before implementation.
• If a fix feels hacky, prefer the cleaner approach you would choose with full context.
• Skip elegance over-optimization for obvious small fixes; do not over-engineer.

Autonomous Bug Fixing

• When given a bug report, own the full path: reproduce, identify root cause, fix, and verify.
• Start from logs, errors, and failing tests; resolve issues with minimal user context switching.
• If CI checks fail in scope, investigate and fix them without waiting for step-by-step instructions.

Task Management (Portable)

• For non-trivial work, maintain a checkable plan in tasks/todo.md.
• Track progress as items are completed and include brief review notes for key decisions.
• Capture recurring corrections and preventions in tasks/lessons.md.
• If tasks/todo.md or tasks/lessons.md does not exist, create it on demand for active work.

Core Principles

• Simplicity first: keep each change as small as possible while solving the right problem.
• No laziness: find and fix root causes, not temporary patches.
• Minimal impact: touch only what is necessary and avoid introducing regressions.

Self-improvement

• After any user correction, update portable task notes (tasks/lessons.md) with mistake-prevention rules.

• Review relevant lessons at the start of related tasks and apply them proactively.

• Iterate on these lessons until repeat mistakes materially drop.

• If we hit the same correction twice, codify it in AGENTS.md so future work stays aligned.

Service Dependencies

• Keep dependency references high-level in this public repository.
• If a change requires deep internal service details, escalate to maintainers and use internal docs for implementation specifics.