# SnagBadger foundation

Status: accepted foundation direction. The user accepts the module-oriented organization and ownership, core technology stack, predefined restylable UI, full production checks for prototypes, and one version for the entire repository. Detailed product interfaces and expanded check configuration belong to follow-up decisions. This document specifies structure, not implemented functionality.

Decision ticket: [Choose repository boundaries and the prototype workspace](https://github.com/CosticaPuntaru/SnagBadger/issues/2).

## Intent

One source-available repository, licensed under PolyForm Shield 1.0.0, contains the website toolkit, integrations, optional server, reusable agent-testing modules, and skills. Organize by product area and deep module, with internal layers inside each module. This supersedes the earlier proposal for global SDK layers. The license choice supersedes the original open-source publishing direction; see the repository [license](../../LICENSE) and [licensing notes](../../README.md#license).

The website toolkit supports plain HTML and other frameworks. Its launcher and framework-independent reporting logic do not eagerly load React. The reporting interface uses React and loads on demand. Library-specific harvesters are distinct from framework embedding adapters.

Agent-driven manual-style UI testing is a first-class workflow. Skills guide setup, test discovery and maintenance, execution, reporting, and regression-test generation. Reusable modules perform predictable work; agents perform exploration and judgment. Test definitions, test-run results, and bug reports remain distinct.

## Intended directory map

This is the full intended structure. **All file and directory paths are illustrative and subject to change, not fixed commitments.** Names, nesting, entry-point filenames, and package locations may change as prototypes establish better depth and locality. Preserve the agreed responsibilities and dependency rules when reorganizing; revisit those explicitly if a change affects them. Future directories are not promises to ship all features in the first release. A directory is not automatically a published package.

```text
sdk/
  reporting/
    src/
      index.ts                     # Framework-independent interface
      browser.ts                   # Optional reporting UI entry
      internal/
        report/
        session/
        configuration/             # Apply reporting-specific policies
        harvesting/
        submission/
        ui/
          composer/
          review/
          settings/
          evidence/
            viewer/
            screenshot-editor/
    tests/
  capture/
    src/
      index.ts
      internal/
        screenshots/
        steps/
        video/
        permissions/
        resources/
    tests/
  embedding/
    src/
      index.ts
      internal/
        launcher/
        loading/
        mounting/
        visibility/
    tests/

agent-testing/
  catalog/                         # Definitions, hierarchy, selection, updates
  execution/                       # Scoped work, coordination, result collection
  reporting/                       # Run artifacts, HTML viewer, failure reporting

integrations/
  configuration/                   # Shared project/destination configuration
  frameworks/
    javascript/
    react/
  harvesters/
    browser/
    react/
    redux/
    zustand/
  providers/
    local/
    jira/
    linear/
  testing/                         # Adapter conformance helpers

server/
  configuration/                   # Serve remote configuration and access policies
  reporting/                       # Receive, persist, and deliver reports
  administration/
  host/                            # Compose modules and expose endpoints
  deployment/
    self-hosted/
    managed/

skills/
  setup/
    initialize-project/
  planning/
    discover-behavior/
    assess-coverage/
    generate-test-plan/
  maintenance/
    add-feature-tests/
    add-bug-tests/
    update-tests/
  execution/
    coordinate-testing/
    execute-ui-scenario/
    consolidate-results/
  reporting/
    create-bug-report/
  regression/
    reproduce-bug/
    generate-regression-test/
  shared/                          # References and thin invocation helpers

examples/
  playground/
    app/
    scenarios/
  plain-html/
  server-connected/

testing/                           # Verification of SnagBadger itself
  fixtures/
  journeys/
  compatibility/
  performance/
  skills/

tooling/
  build/
  release/
  github-pages/

docs/
  architecture/
  integration/
  contributing/
  prototypes/
  adr/
  agents/

.github/workflows/
GLOSSARY.md
```

The abbreviated modules follow `src/`, private implementation folders, and `tests/` where applicable. Future skill names describe intended workflows; their exact granularity will be tested rather than creating overlapping prompts in advance.

## Module ownership and depth

| Module                    | Complexity hidden behind its interface                                                          |
| ------------------------- | ----------------------------------------------------------------------------------------------- |
| SDK reporting             | Bug-report lifecycle, validation, evidence, harvester coordination, review, and submission      |
| SDK capture               | Capture mechanisms, browser permissions, recording state, and resource cleanup                  |
| SDK embedding             | Host installation, visibility, deferred loading, mounting, and teardown                         |
| Agent-testing catalog     | Test identity, hierarchy, selection, and updates from features or bugs                          |
| Agent-testing execution   | Scoped work allocation, delegated execution, result collection, and budgets                     |
| Agent-testing reporting   | Run artifacts, evidence navigation, HTML rendering, and conversion of failures into bug reports |
| Integration configuration | Resolve reusable project/destination configuration for each execution environment               |

These are candidate seams to validate through prototypes. Embedding must earn its depth rather than become a forwarding wrapper. A dedicated standalone JavaScript integration package is also conditional: use the embedding interface directly if another adapter adds no leverage.

### Shared configuration without duplicated responsibility

Integration configuration owns reusable configuration composition and resolution. SDK reporting interprets the resulting settings for an individual reporting session. Consumers must not implement competing precedence rules. Initial configuration is developer-supplied and resolved at initialization; built-in remote configuration is deferred to a future extension and the optional server decision.

The in-app reporter, reporting skills, and test-run HTML viewer support reusable destination configuration and submission behavior. A project may share `snagBadger.config.ts`, supply separate configurations, or compose consumer-specific configurations through helpers; sharing is optional. The HTML viewer renders a complete run and can create a bug report from a selected failure. These consumers do not share a single all-purpose report model. Privileged credentials are resolved in the appropriate execution environment, not copied into exported HTML.

## Dependency and loading rules

- Each module owns its interface and exports the types callers need; no global collection of unrelated contracts.
- External callers import supported entries, never another module's `internal/` folders.
- Framework-independent reporting entries must not import React, browser globals, or server-only libraries at load time.
- Embedding loads the browser reporting interface and capture capabilities on demand. Separately loaded code need not be a separate package.
- Reporting coordinates capture through a deliberately designed seam; capture does not import reporting UI. Shared evidence representation is settled in the report-model ticket, avoiding circular imports.
- Providers and harvesters satisfy interfaces owned by their consumers. Callers supply selected adapters rather than core code importing every integration.
- The React host adapter is distinct from the React diagnostic harvester.
- Agent-testing reporting uses the bug-reporting interface when producing a bug report, while retaining its own test-run semantics.
- Skills invoke reusable modules for deterministic work. They do not duplicate serializers, HTML rendering, provider logic, or test-selection behavior in prompts.
- Server modules may use portable interfaces; they must not require browser UI or a browser runtime.

### Architecture checks

Evaluate depth, leverage, and locality. Use the interface as the test surface. Apply the deletion test to pass-through modules. Validate hypothetical seams with a second realistic adapter before generalizing. Interface design includes lifecycle, errors, configuration, and performance obligations, not only signatures.

Keep module tests beside their module. Reserve root `testing/` for shared fixtures and cross-module verification; it is not the product's test catalog. Measure inactive, first-open, recording, and teardown behavior. Agent execution additionally measures context/token use and the cost of retrieving evidence.

## Workspace packages versus internal folders

Candidate workspace-package roots are the three SDK modules, three agent-testing modules, integration configuration, and individual concrete integrations with meaningful dependencies. Their nested feature folders remain implementation details unless a prototype demonstrates independent consumers or another substantial reason to extract them.

Server package granularity is intentionally deferred to its roadmap ticket. Use one version for the entire repository: all versioned packages and released skill/server artifacts belong to the same release. Maintain one authoritative version and mechanically verify synchronized metadata. Private examples and tooling need not become published packages. Automate version changes; independently versioned release families are not part of this foundation.

## Technology and consumption direction

Use strict TypeScript, Node.js LTS, pnpm workspaces, Vite for browser builds, React for optional reporting interfaces, Vitest for module verification, and Playwright for real-browser verification. Deploy static examples through GitHub Actions to GitHub Pages. Exact versions and server framework/storage choices are not selected here.

The UI direction is shadcn/ui and Tailwind. Provide three consumption levels: functions without a supplied UI, predefined components with supported styling/customization hooks, and fully styled ready-to-use UI. White-label means consumers can restyle supplied components; it does not require them to assemble an unstyled UI from primitives. Exact styling hooks and distribution mechanisms remain implementation-design questions. Functions must remain consumable without importing React, UI styles, or unrelated integrations. Apply the same optional-UI principle to agent-testing artifacts and HTML rendering where relevant.

Developer-composed configuration with optional helpers and presets is an established SnagBadger design pattern. Developers can set behavior directly, use customizable profiles, nest selectors for hosts, environment variables and custom checks, or compose different settings for different consumers. Helpers provide convenience without becoming mandatory structure. Profile names such as dev and public impose no special runtime permission modes; their settings determine behavior. Convenience compositions should conceal coordination rather than requiring callers to assemble implementation details. The Valibot comparison describes the developer experience, not a schema-library selection or a performance claim.

The accepted [configuration and permissions decision](./configuration.md), with its [canonical tracker resolution](https://github.com/CosticaPuntaru/SnagBadger/issues/5#issuecomment-6101197512), records the policy scope, configurable history and reporter controls, host-owned access decisions, and deferred implementation details. Future module designs should follow this pattern; exact helper names and signatures remain implementation decisions.

## Strict repository quality direction

Treat automated enforcement as part of the foundation: strict typing, linting, formatting, dependency/import checks, and file-path conventions. Build a maintained system for project-specific lint rules, meaningful rule tests, and regression checks for the quality tooling itself. Define enforceable architecture checks for private imports, browser/server separation, optional UI loading, and module dependencies.

Illustrative directory paths remain changeable. Once a naming/layout convention is agreed, enforce it mechanically; update the convention and its checks deliberately when reorganizing. These are compatible requirements: evolving architecture does not mean arbitrary paths.

All prototypes must satisfy the same full strict quality policy as production code from the start. There is no reduced prototype rule set or exemption based on an experiment being temporary. The exact lint/formatter configuration, enforcement points, and any general exception process require a concrete policy before implementation. Code coverage percentages and numbers of lint rules are not substitutes for verifying behavior and relevant failure modes.

## Minimum scaffold implementation handoff

The next implementation should establish the workspace, not build the reporting product:

1. Add workspace tooling and minimal SDK package shells for reporting, capture, and embedding. Encode supported entries and import restrictions, without inventing final behavioral interfaces.
2. Add the React playground and plain-HTML example, with one reproducible bug scenario and its fixed behavior. Keep scenario definitions close to the playground; share only fixtures actually used elsewhere.
3. Provide local development and a static build that can deploy both examples through GitHub Pages, including deployment subpaths. Initial examples must not depend on the optional server.
4. Add basic build/type checks and a smoke check proving both examples load. Introduce behavioral tests as behavior appears, rather than tests of empty scaffolding.
5. Document the rest of the intended tree and prototype conventions. Create future packages when their first experiment needs them; avoid empty packages solely to reproduce the diagram.

The first integrated product demonstration remains launcher -> reproduce -> capture -> configured review -> local export. Test planning and bug-to-test skills are initial AI priorities; layered autonomous execution comes later. Project setup is a prerequisite to usable skills, not an excuse to postpone that first useful path.

## Prototype and research assets

Prototypes are evolutionary work intended to be able to become production code, not throwaway implementations. Develop experiments in the maintained module structure, using descriptive feature/prototype branches as appropriate, under the complete production quality policy. Keep experiments scoped and require human feedback to settle their design questions. Accepted code and regression scenarios can enter maintained modules/examples through reviewed implementation changes without relaxing checks or requiring an automatic rewrite. Rejected experiments need not be shipped. Research remains on `research/<name>` branches with linked findings.

This standing user instruction overrides any default prototype-skill guidance that assumes disposable implementation or relaxed prototype standards. Foundation planning still does not itself authorize building the product.

The issue tracker is the canonical decision record. This document is the architecture asset for the foundation ticket. Exact report/configuration schemas, browser support, capture controls, server responsibilities, HTML-report hosting/submission, agent-runtime adapters, and performance/token budgets remain with their existing decision tickets.