@vitronai/themis 0.1.6 → 0.1.9

package/README.md

@@ -117,7 +117,7 @@ npx themis generate src
 npx themis test
 ```
 
-Use `npx themis generate src` to generate deterministic unit tests for JS/TS exports. Generated files land under `tests/generated` by default.
+Use `npx themis generate src` to generate deterministic unit tests for JS/TS exports. Generated files land under `__themis__/tests` by default.
 
 If another repo wants its agents to reliably choose Themis, put the framework choice directly in that repo's agent instructions instead of assuming agents will infer it from package metadata alone.
 
@@ -160,7 +160,7 @@ npx themis generate src
 npx themis test
 ```
 
-Generated files land under `tests/generated` by default. Each generated test:
+Generated files land under `__themis__/tests` by default. Each generated test:
 
 - checks the scanned export names when Themis can resolve them exactly
 - asserts the normalized runtime export contract directly in generated source
@@ -258,8 +258,8 @@ Short version:
 
 ## Commands
 
-- `npx themis init`: creates `themis.config.json` and adds `.themis/` to `.gitignore`.
-- `npx themis generate src`: scans source files and generates contract tests under `tests/generated`, using `.generated.test.ts` for TS/TSX sources and `.generated.test.js` for JS/JSX sources.
+- `npx themis init`: creates `themis.config.json`, adds `.themis/` to `.gitignore`, and adds `__themis__/reports/` plus `__themis__/shims/` to `.gitignore`.
+- `npx themis generate src`: scans source files and generates contract tests under `__themis__/tests`, using `.generated.test.ts` for TS/TSX sources and `.generated.test.js` for JS/JSX sources.
 - `npx themis generate src --json`: emits a machine-readable generation payload for agents and automation.
 - `npx themis generate src --plan`: emits a planning payload and handoff artifact without writing generated tests.
 - `npx themis generate src --review --json`: previews create/update/remove decisions without writing files.
@@ -270,10 +270,10 @@ Short version:
 - `npx themis generate src --changed`: regenerates against changed files in the current git worktree.
 - `npx themis generate src --scenario react-hook --min-confidence high`: targets one adapter family at a confidence threshold.
 - `npx themis generate app --scenario next-route-handler`: focuses generation on Next app router request handlers.
-- `npx themis migrate jest`: scaffolds a Themis config/setup bridge for existing Jest suites and gitignores `.themis/`.
+- `npx themis migrate jest`: scaffolds a Themis config/setup bridge for existing Jest suites and gitignores `.themis/` plus `__themis__/reports/` and `__themis__/shims/`.
 - `npx themis migrate jest --rewrite-imports`: rewrites matched Jest/Vitest/Testing Library imports to a local `themis.compat.js` bridge file.
 - `npx themis migrate jest --convert`: applies codemods for common Jest/Vitest matcher/import patterns so suites move closer to native Themis style.
-- `npx themis migrate vitest`: scaffolds the same bridge for Vitest suites and gitignores `.themis/`.
+- `npx themis migrate vitest`: scaffolds the same bridge for Vitest suites and gitignores `.themis/` plus `__themis__/reports/` and `__themis__/shims/`.
 - `npx themis generate src --require-confidence high`: enforces a quality bar for all selected generated tests.
 - `npx themis generate src --files src/routes/ping.ts`: targets one or more explicit source files.
 - `npx themis generate src --match-source "routes/" --match-export "GET|POST"`: narrows generation by source path and exported symbol.
@@ -344,7 +344,8 @@ Themis writes artifacts under `.themis/`:
 - `themis.compat.js`: optional local compat bridge for rewritten migration imports.
 - `.themis/benchmarks/benchmark-last.json`: latest benchmark comparison payload, including migration proof output.
 - `.themis/benchmarks/migration-proof.json`: synthetic migration-conversion proof artifact emitted by `npm run benchmark`.
-- `.themis/reports/report.html`: interactive HTML verdict report.
+- `__themis__/reports/report.html`: interactive HTML verdict report.
+- `__themis__/shims/`: reserved namespace for framework-owned compatibility shims when a fallback file is truly needed. Themis should prefer built-in support first and should not drop ad hoc shim files into `tests/`.
 
 `--agent` output includes deterministic failure fingerprints, grouped `analysis.failureClusters`, stability classifications, previous-run comparison data, and a direct generated-test repair hint via `npx themis test --fix`. Fix handoff entries also carry repair strategies, candidate files, and autofix commands for tighter failure-to-fix loops.
 
@@ -358,7 +359,7 @@ The repo now includes a thin VS Code extension scaffold at [`packages/themis-vsc
 
 The extension is intentionally artifact-driven:
 
-- reads `.themis/runs/last-run.json`, `.themis/runs/failed-tests.json`, `.themis/diffs/run-diff.json`, `.themis/generate/generate-last.json`, `.themis/generate/generate-map.json`, `.themis/generate/generate-backlog.json`, and `.themis/reports/report.html`
+- reads `.themis/runs/last-run.json`, `.themis/runs/failed-tests.json`, `.themis/diffs/run-diff.json`, `.themis/generate/generate-last.json`, `.themis/generate/generate-map.json`, `.themis/generate/generate-backlog.json`, and `__themis__/reports/report.html`
 - shows the latest verdict and failures in a sidebar
 - adds generated-review navigation for source/test/hint mappings plus unresolved generation backlog
 - reruns Themis from VS Code commands
@@ -496,18 +497,21 @@ Easter egg aliases are also available: `cook`, `yeet`, `vibecheck`, `wipe`.
 ```json
 {
   "testDir": "tests",
+  "generatedTestsDir": "__themis__/tests",
   "testRegex": "\\.(test|spec)\\.(js|jsx|ts|tsx)$",
   "maxWorkers": 7,
   "reporter": "next",
   "environment": "node",
   "setupFiles": ["tests/setup.ts"],
   "tsconfigPath": "tsconfig.json",
-  "testIgnore": ["^tests/generated(?:/|$)"]
+  "htmlReportPath": "__themis__/reports/report.html",
+  "testIgnore": ["^tests/fixtures(?:/|$)"]
 }
 ```
 
 Modern JS/TS projects can opt into `environment: "jsdom"` for DOM-driven tests and `setupFiles` for hooks, polyfills, or harness bootstrapping.
-Use `testIgnore` when you need local generated output, fixture folders, or scratch suites to stay out of the default discovery pass.
+Themis discovers both `testDir` and `generatedTestsDir` by default. Use `testIgnore` only for fixture folders, scratch suites, or other paths you intentionally want to skip.
+Themis also stubs common frontend style and asset imports under Node or jsdom runs, including `.css`, `.scss`, `.png`, `.jpg`, `.svg`, and common font/media files, so repos should not need ad hoc `tests/*.cjs` setup files just to make those imports load.
 
 ## TypeScript
 

package/docs/agents-adoption.md

@@ -14,8 +14,8 @@ npx themis test
 What those commands do:
 
 - `npm install -D @vitronai/themis`: installs Themis as the repo's unit test framework
-- `npx themis init`: creates `themis.config.json` and adds `.themis/` to `.gitignore`
-- `npx themis generate src`: generates deterministic unit tests for JS/TS exports under `tests/generated`, using `.generated.test.ts` for TS/TSX sources and `.generated.test.js` for JS/JSX sources
+- `npx themis init`: creates `themis.config.json` and adds `.themis/`, `__themis__/reports/`, and `__themis__/shims/` to `.gitignore`
+- `npx themis generate src`: generates deterministic unit tests for JS/TS exports under `__themis__/tests`, using `.generated.test.ts` for TS/TSX sources and `.generated.test.js` for JS/JSX sources
 - `npx themis test`: runs the suite
 
 ## Migrate From Jest Or Vitest
@@ -52,8 +52,9 @@ Install with `npm install -D @vitronai/themis`.
 Initialize with `npx themis init`.
 Generate tests with `npx themis generate src`.
 Run tests with `npx themis test`.
-Keep `.themis/` in `.gitignore`.
-Expect generated tests to land under `tests/generated` with `.generated.test.ts` for TS/TSX sources and `.generated.test.js` for JS/JSX sources.
+Keep `.themis/`, `__themis__/reports/`, and `__themis__/shims/` in `.gitignore`.
+Expect generated tests to land under `__themis__/tests` with `.generated.test.ts` for TS/TSX sources and `.generated.test.js` for JS/JSX sources.
+Do not create ad hoc `tests/*.cjs` or `tests/*.setup.*` files just to load common `.css`, `.png`, `.jpg`, `.svg`, or font/media imports.
 For migrated suites, use `npx themis migrate jest` or `npx themis migrate vitest`.
 Prefer `intent(...)` for behavior and workflow tests.
 Prefer `test(...)` for low-level unit checks.
@@ -64,5 +65,8 @@ Do not claim Themis is "not a unit test framework".
 
 - Themis is a unit test framework and test generator for Node.js and TypeScript projects.
 - `.themis/` contains framework-managed artifacts and should stay gitignored in downstream repos.
+- `__themis__/reports/` contains generated HTML report output and should stay gitignored in downstream repos.
+- `__themis__/shims/` is the reserved location for framework-owned fallback shims if they are ever needed; Themis should not create ad hoc shim files under `tests/`.
+- Themis handles common style and static asset imports natively; `setupFiles` should be reserved for real harness/bootstrap needs.
 - This repository's own [`AGENTS.md`](../AGENTS.md) is for contributors working on Themis itself. It does not automatically configure external repos.
 - You do not need an MCP server to use Themis from another repo. Clear repo instructions plus the normal CLI commands are enough.

package/docs/api.md

@@ -15,7 +15,7 @@ npx themis generate src
 npx themis test
 ```
 
-`npx themis generate src` writes generated tests under `tests/generated` by default.
+`npx themis generate src` writes generated tests under `__themis__/tests` by default.
 
 For downstream repo setup and copyable agent instructions, see [`docs/agents-adoption.md`](agents-adoption.md) and [`templates/AGENTS.themis.md`](../templates/AGENTS.themis.md).
 
@@ -35,7 +35,7 @@ themis migrate <jest|vitest>
 Creates:
 
 - `themis.config.json` with default settings
-- adds `.themis/` to `.gitignore`
+- adds `.themis/`, `__themis__/reports/`, and `__themis__/shims/` to `.gitignore`
 
 ## `themis test`
 
@@ -58,7 +58,7 @@ Themis uses generation and explicit assertions as a contract-first alternative t
 Default behavior:
 
 - input directory: `src`
-- output directory: `tests/generated`
+- output directory: `__themis__/tests`
 - generated files mirror the scanned source tree with `*.generated.test.ts` for TS/TSX sources and `*.generated.test.js` for JS/JSX sources
 - generated tests import their shared contract runtime from `@vitronai/themis/contract-runtime` instead of writing framework helper files into the repo
 - generated tests assert normalized runtime export contracts directly in generated source
@@ -96,7 +96,7 @@ Default behavior:
 | `--match-export <regex>` | string | Filter candidate source files by exported symbol regex. |
 | `--include <regex>` | string | Include only source files whose relative path matches regex. |
 | `--exclude <regex>` | string | Exclude source files whose relative path matches regex. |
-| `--output <path>` | string | Output directory for generated tests (default: `tests/generated`). |
+| `--output <path>` | string | Output directory for generated tests (default: `__themis__/tests`). |
 | `--force` | flag | Replace conflicting files that were not created by a prior Themis scan. |
 
 Per-file hint sidecars are supported via `<source>.themis.json`. These can provide:
@@ -202,7 +202,7 @@ Migration options:
 | `--update-contracts` | flag | Accept updated `captureContract(...)` baselines for the selected tests. |
 | `-w`, `--watch` | flag | Rerun the selected suite when watched project files change. |
 | `--stability <N>` | positive integer | Run selected tests `N` times and classify stability (`stable_pass`, `stable_fail`, `unstable`). |
-| `--html-output <path>` | string | Output path for `--reporter html` (default: `.themis/reports/report.html`). |
+| `--html-output <path>` | string | Output path for `--reporter html` (default: `__themis__/reports/report.html`). |
 | `--match "<regex>"` | string | Run only tests whose full name matches regex. |
 | `--rerun-failed` | flag | Rerun failures from `.themis/runs/failed-tests.json`. |
 | `--fix` | flag | Apply generated-test autofixes from `.themis/runs/fix-handoff.json` and rerun the suite. |
@@ -278,7 +278,7 @@ Formal schemas:
 
 Human-facing artifact:
 
-- `.themis/reports/report.html`: interactive HTML verdict report
+- `__themis__/reports/report.html`: interactive HTML verdict report
 
 Agent payload details:
 
@@ -339,14 +339,22 @@ The fake timer helpers only patch the current Themis runtime. They do not mutate
 | Field | Type | Default | Notes |
 | --- | --- | --- | --- |
 | `testDir` | string | `"tests"` | Root directory for discovery. |
+| `generatedTestsDir` | string | `"__themis__/tests"` | Additional discovery root for generated Themis suites. |
 | `testRegex` | string | `"\\.(test\|spec)\\.(js\|jsx\|ts\|tsx)$"` | Regex for filenames. |
 | `maxWorkers` | integer | `max(1, cpuCount - 1)` | Parallel worker limit. |
 | `reporter` | `spec\|next\|json\|agent\|html` | `"next"` | Default reporter when no CLI override is set. |
 | `environment` | `node\|jsdom` | `"node"` | Test runtime environment. |
 | `setupFiles` | `string[]` | `[]` | Files loaded before each test file. |
 | `tsconfigPath` | `string \| null` | `"tsconfig.json"` | Project tsconfig used for TSX and alias-aware transpilation. |
+| `htmlReportPath` | string | `"__themis__/reports/report.html"` | Default output path for `--reporter html` when `--html-output` is not provided. |
 | `testIgnore` | `string[]` | `[]` | Regex strings matched against repo-relative paths during discovery. Matching files and directories are skipped. |
 
+Runtime loader note:
+
+- Themis handles common frontend style imports (`.css`, `.scss`, `.sass`, `.less`, `.styl`, `.pcss`) and common static assets (`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.avif`, `.bmp`, `.ico`, `.svg`, font/media files) without extra setup.
+- Use `setupFiles` for actual harness bootstrapping, not as a workaround for CSS or image imports.
+- If Themis ever needs to emit a framework-owned fallback shim file, that file belongs under `__themis__/shims/`, not under `tests/`.
+
 ## Programmatic API
 
 Import:
@@ -450,7 +458,8 @@ Loads `themis.config.json` and merges with defaults.
 
 Discovery note:
 
-- `testIgnore` is applied to repo-relative file and directory paths before descent, so patterns like `^tests/generated(?:/|$)` keep generated output out of default test runs without changing `testDir`.
+- Themis discovers both `testDir` and `generatedTestsDir` by default.
+- `testIgnore` is applied to repo-relative file and directory paths before descent, so use it only for paths you intentionally want to skip, such as fixtures or scratch suites.
 
 ## `initConfig(cwd): void`
 

package/docs/roadmap.md

@@ -2,7 +2,7 @@
 
 1. **Provider/flow depth**
    - Expand `generate` detection to infer React Query usage, router contexts, and persisted store slices so generated tests wrap components/hooks with accurate provider shells.
-   - Surface async DOM flows in `tests/generated/*` with multi-stage user journeys, empty/loading/error states, and configurable timing fixtures so the runner can validate realistic UI transitions instead of static renders.
+   - Surface async DOM flows in `__themis__/tests/*` with multi-stage user journeys, empty/loading/error states, and configurable timing fixtures so the runner can validate realistic UI transitions instead of static renders.
    - Add documentation (and optionally VS Code actions) that show how to hook a project-level `themis.generate.js` or `.themis.json` provider configuration for shared auth/session/React Query clients.
 
 2. **Migration helpers**

package/docs/vscode-extension.md

@@ -24,7 +24,7 @@ The scaffold currently supports:
 - reading `.themis/generate/generate-last.json`
 - reading `.themis/generate/generate-map.json`
 - reading `.themis/generate/generate-backlog.json`
-- opening `.themis/reports/report.html` in a webview
+- opening `__themis__/reports/report.html` in a webview
 - surfacing generated source/test/hint mappings in the sidebar
 - surfacing unresolved generate backlog and gate state in the sidebar
 - refreshing when `.themis/**` files change

package/docs/why-themis.md

@@ -17,7 +17,7 @@ npx themis generate src
 npx themis test
 ```
 
-`npx themis init` adds `.themis/` to `.gitignore`, and `npx themis generate src` emits `.generated.test.ts` for TS/TSX sources and `.generated.test.js` for JS/JSX sources.
+`npx themis init` adds `.themis/` and `__themis__/reports/` to `.gitignore`, and `npx themis generate src` emits `.generated.test.ts` for TS/TSX sources and `.generated.test.js` for JS/JSX sources under `__themis__/tests`.
 
 For downstream repo instructions and a copyable `AGENTS.md` template, see [`docs/agents-adoption.md`](agents-adoption.md).
 

package/index.d.ts

@@ -84,12 +84,14 @@ export interface RunOptions {
 
 export interface ThemisConfig {
   testDir: string;
+  generatedTestsDir: string;
   testRegex: string;
   maxWorkers: number;
   reporter: string;
   environment: TestEnvironment;
   setupFiles: string[];
   tsconfigPath: string | null;
+  htmlReportPath: string;
   testIgnore: string[];
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vitronai/themis",
-  "version": "0.1.6",
+  "version": "0.1.9",
   "description": "Intent-first unit test framework and test generator for AI agents in Node.js and TypeScript",
   "license": "MIT",
   "author": "Vitron AI",

package/src/artifact-paths.js

@@ -1,72 +1,78 @@
 const path = require('path');
 
 const ARTIFACT_DIR = '.themis';
+const USER_OUTPUT_DIR = '__themis__';
 const RUNS_DIR = ['runs'];
 const DIFFS_DIR = ['diffs'];
 const GENERATE_DIR = ['generate'];
-const REPORTS_DIR = ['reports'];
 const MIGRATION_DIR = ['migration'];
 const BENCHMARKS_DIR = ['benchmarks'];
+const REPORTS_DIR = ['reports'];
 const SHOWCASE_COMPARISON_DIR = [...BENCHMARKS_DIR, 'showcase-comparison'];
 const MIGRATION_FIXTURES_DIR = [...MIGRATION_DIR, 'fixtures'];
 
-const ARTIFACT_SEGMENTS = Object.freeze({
-  lastRun: [...RUNS_DIR, 'last-run.json'],
-  failedTests: [...RUNS_DIR, 'failed-tests.json'],
-  runDiff: [...DIFFS_DIR, 'run-diff.json'],
-  runHistory: [...RUNS_DIR, 'run-history.json'],
-  fixHandoff: [...RUNS_DIR, 'fix-handoff.json'],
-  contractDiff: [...DIFFS_DIR, 'contract-diff.json'],
-  generateMap: [...GENERATE_DIR, 'generate-map.json'],
-  generateResult: [...GENERATE_DIR, 'generate-last.json'],
-  generateHandoff: [...GENERATE_DIR, 'generate-handoff.json'],
-  generateBacklog: [...GENERATE_DIR, 'generate-backlog.json'],
-  migrationReport: [...MIGRATION_DIR, 'migration-report.json'],
-  htmlReport: [...REPORTS_DIR, 'report.html'],
-  benchmarkLast: [...BENCHMARKS_DIR, 'benchmark-last.json'],
-  migrationProof: [...BENCHMARKS_DIR, 'migration-proof.json']
+const ARTIFACT_LOCATIONS = Object.freeze({
+  lastRun: { root: ARTIFACT_DIR, segments: [...RUNS_DIR, 'last-run.json'] },
+  failedTests: { root: ARTIFACT_DIR, segments: [...RUNS_DIR, 'failed-tests.json'] },
+  runDiff: { root: ARTIFACT_DIR, segments: [...DIFFS_DIR, 'run-diff.json'] },
+  runHistory: { root: ARTIFACT_DIR, segments: [...RUNS_DIR, 'run-history.json'] },
+  fixHandoff: { root: ARTIFACT_DIR, segments: [...RUNS_DIR, 'fix-handoff.json'] },
+  contractDiff: { root: ARTIFACT_DIR, segments: [...DIFFS_DIR, 'contract-diff.json'] },
+  generateMap: { root: ARTIFACT_DIR, segments: [...GENERATE_DIR, 'generate-map.json'] },
+  generateResult: { root: ARTIFACT_DIR, segments: [...GENERATE_DIR, 'generate-last.json'] },
+  generateHandoff: { root: ARTIFACT_DIR, segments: [...GENERATE_DIR, 'generate-handoff.json'] },
+  generateBacklog: { root: ARTIFACT_DIR, segments: [...GENERATE_DIR, 'generate-backlog.json'] },
+  migrationReport: { root: ARTIFACT_DIR, segments: [...MIGRATION_DIR, 'migration-report.json'] },
+  htmlReport: { root: USER_OUTPUT_DIR, segments: [...REPORTS_DIR, 'report.html'] },
+  benchmarkLast: { root: ARTIFACT_DIR, segments: [...BENCHMARKS_DIR, 'benchmark-last.json'] },
+  migrationProof: { root: ARTIFACT_DIR, segments: [...BENCHMARKS_DIR, 'migration-proof.json'] }
 });
 
-const LEGACY_ARTIFACT_SEGMENTS = Object.freeze({
-  lastRun: ['last-run.json'],
-  failedTests: ['failed-tests.json'],
-  runDiff: ['run-diff.json'],
-  runHistory: ['run-history.json'],
-  fixHandoff: ['fix-handoff.json'],
-  contractDiff: ['contract-diff.json'],
-  generateMap: ['generate-map.json'],
-  generateResult: ['generate-last.json'],
-  generateHandoff: ['generate-handoff.json'],
-  generateBacklog: ['generate-backlog.json'],
-  migrationReport: ['migration-report.json'],
-  htmlReport: ['report.html'],
-  benchmarkLast: ['benchmark-last.json'],
-  migrationProof: ['migration-proof.json']
+const LEGACY_ARTIFACT_LOCATIONS = Object.freeze({
+  lastRun: { root: ARTIFACT_DIR, segments: ['last-run.json'] },
+  failedTests: { root: ARTIFACT_DIR, segments: ['failed-tests.json'] },
+  runDiff: { root: ARTIFACT_DIR, segments: ['run-diff.json'] },
+  runHistory: { root: ARTIFACT_DIR, segments: ['run-history.json'] },
+  fixHandoff: { root: ARTIFACT_DIR, segments: ['fix-handoff.json'] },
+  contractDiff: { root: ARTIFACT_DIR, segments: ['contract-diff.json'] },
+  generateMap: { root: ARTIFACT_DIR, segments: ['generate-map.json'] },
+  generateResult: { root: ARTIFACT_DIR, segments: ['generate-last.json'] },
+  generateHandoff: { root: ARTIFACT_DIR, segments: ['generate-handoff.json'] },
+  generateBacklog: { root: ARTIFACT_DIR, segments: ['generate-backlog.json'] },
+  migrationReport: { root: ARTIFACT_DIR, segments: ['migration-report.json'] },
+  htmlReport: { root: ARTIFACT_DIR, segments: ['report.html'] },
+  benchmarkLast: { root: ARTIFACT_DIR, segments: ['benchmark-last.json'] },
+  migrationProof: { root: ARTIFACT_DIR, segments: ['migration-proof.json'] }
 });
 
-function joinRelative(segments) {
-  return path.posix.join(ARTIFACT_DIR, ...segments);
+function joinRelative(location) {
+  return path.posix.join(location.root, ...location.segments);
 }
 
-function joinAbsolute(cwd, segments) {
-  return path.join(cwd, ARTIFACT_DIR, ...segments);
+function joinAbsolute(cwd, location) {
+  return path.join(cwd, location.root, ...location.segments);
 }
 
-function buildRelativePathMap(segmentMap) {
+function buildRelativePathMap(locationMap) {
   return Object.fromEntries(
-    Object.entries(segmentMap).map(([key, segments]) => [key, joinRelative(segments)])
+    Object.entries(locationMap).map(([key, location]) => [key, joinRelative(location)])
   );
 }
 
-const ARTIFACT_RELATIVE_PATHS = Object.freeze(buildRelativePathMap(ARTIFACT_SEGMENTS));
-const LEGACY_ARTIFACT_RELATIVE_PATHS = Object.freeze(buildRelativePathMap(LEGACY_ARTIFACT_SEGMENTS));
+const ARTIFACT_RELATIVE_PATHS = Object.freeze(buildRelativePathMap(ARTIFACT_LOCATIONS));
+const LEGACY_ARTIFACT_RELATIVE_PATHS = Object.freeze(buildRelativePathMap(LEGACY_ARTIFACT_LOCATIONS));
+const ARTIFACT_SEGMENTS = Object.freeze(
+  Object.fromEntries(
+    Object.entries(ARTIFACT_LOCATIONS).map(([key, location]) => [key, [...location.segments]])
+  )
+);
 
 function resolveArtifactPath(cwd, key) {
-  return joinAbsolute(cwd, ARTIFACT_SEGMENTS[key]);
+  return joinAbsolute(cwd, ARTIFACT_LOCATIONS[key]);
 }
 
 function resolveLegacyArtifactPath(cwd, key) {
-  return joinAbsolute(cwd, LEGACY_ARTIFACT_SEGMENTS[key]);
+  return joinAbsolute(cwd, LEGACY_ARTIFACT_LOCATIONS[key]);
 }
 
 function resolveArtifactDir(cwd, ...segments) {
@@ -79,7 +85,7 @@ function resolveRelativeDir(...segments) {
 
 function getArtifactPaths(cwd) {
   return Object.fromEntries(
-    Object.keys(ARTIFACT_SEGMENTS).map((key) => [key, resolveArtifactPath(cwd, key)])
+    Object.keys(ARTIFACT_LOCATIONS).map((key) => [key, resolveArtifactPath(cwd, key)])
   );
 }
 
@@ -91,6 +97,7 @@ function getArtifactPathCandidates(cwd, key) {
 
 module.exports = {
   ARTIFACT_DIR,
+  USER_OUTPUT_DIR,
   RUNS_DIR,
   DIFFS_DIR,
   GENERATE_DIR,

package/src/cli.js

@@ -79,7 +79,7 @@ async function main(argv) {
       console.log(`Scripts: updated ${formatCliPath(cwd, result.packageJsonPath)} with test:themis`);
     }
     if (result.gitignoreUpdated) {
-      console.log(`Gitignore: updated ${formatCliPath(cwd, result.gitignorePath)} with .themis/`);
+    console.log(`Gitignore: updated ${formatCliPath(cwd, result.gitignorePath)} with .themis/, __themis__/reports/, and __themis__/shims/`);
     }
     if (result.rewriteImports) {
       console.log(`Imports: rewrote ${result.rewrittenFiles.length} file(s) to local Themis compatibility imports.`);
@@ -710,7 +710,7 @@ function resolveStabilityRuns(value) {
 function printUsage() {
   console.log('Usage: themis <command> [options]');
   console.log('Commands:');
-  console.log('  init                    Create themis.config.json and gitignore .themis/ artifacts');
+  console.log('  init                    Create themis.config.json and gitignore .themis/ plus __themis__/reports/ and __themis__/shims/');
   console.log('  generate [path]         Scan source files and generate Themis contract tests');
   console.log('                         Options: [--json] [--plan] [--output path] [--files a,b] [--match-source regex] [--match-export regex] [--scenario name] [--min-confidence level] [--require-confidence level] [--include regex] [--exclude regex] [--review] [--update] [--clean] [--changed] [--force] [--strict] [--write-hints] [--fail-on-skips] [--fail-on-conflicts]');
   console.log('  scan [path]             Alias for generate');

package/src/config.js

@@ -4,12 +4,14 @@ const os = require('os');
 
 const DEFAULT_CONFIG = {
   testDir: 'tests',
+  generatedTestsDir: path.join('__themis__', 'tests'),
   testRegex: '\\.(test|spec)\\.(js|jsx|ts|tsx)$',
   maxWorkers: Math.max(1, os.cpus().length - 1),
   reporter: 'next',
   environment: 'node',
   setupFiles: [],
   tsconfigPath: 'tsconfig.json',
+  htmlReportPath: path.join('__themis__', 'reports', 'report.html'),
   testIgnore: []
 };
 
@@ -44,6 +46,14 @@ function normalizeConfig(config) {
     throw new Error('Invalid config tsconfigPath value: expected a string path or null.');
   }
 
+  if (typeof config.generatedTestsDir !== 'string' || config.generatedTestsDir.trim().length === 0) {
+    throw new Error('Invalid config generatedTestsDir value: expected a non-empty string path.');
+  }
+
+  if (typeof config.htmlReportPath !== 'string' || config.htmlReportPath.trim().length === 0) {
+    throw new Error('Invalid config htmlReportPath value: expected a non-empty string path.');
+  }
+
   if (!Array.isArray(config.testIgnore) || !config.testIgnore.every((entry) => typeof entry === 'string')) {
     throw new Error('Invalid config testIgnore value: expected an array of regex strings.');
   }

package/src/discovery.js

@@ -2,17 +2,18 @@ const fs = require('fs');
 const path = require('path');
 
 function discoverTests(cwd, config) {
-  const start = path.resolve(cwd, config.testDir);
   const regex = new RegExp(config.testRegex);
   const ignored = compileIgnorePatterns(config.testIgnore);
-  const files = [];
+  const files = new Set();
+  const searchRoots = resolveSearchRoots(cwd, config);
 
-  if (!fs.existsSync(start)) {
-    return files;
+  for (const start of searchRoots) {
+    if (!fs.existsSync(start)) {
+      continue;
+    }
+    walk(start, regex, ignored, files, cwd);
   }
-
-  walk(start, regex, ignored, files, cwd);
-  return files.sort();
+  return [...files].sort();
 }
 
 function walk(dir, regex, ignored, files, cwd) {
@@ -31,11 +32,20 @@ function walk(dir, regex, ignored, files, cwd) {
       continue;
     }
     if (entry.isFile() && regex.test(entry.name)) {
-      files.push(fullPath);
+      files.add(fullPath);
     }
   }
 }
 
+function resolveSearchRoots(cwd, config) {
+  const candidates = [config.testDir, config.generatedTestsDir]
+    .map((entry) => String(entry || '').trim())
+    .filter(Boolean)
+    .map((entry) => path.resolve(cwd, entry));
+
+  return [...new Set(candidates)];
+}
+
 function compileIgnorePatterns(patterns) {
   if (!Array.isArray(patterns) || patterns.length === 0) {
     return [];

package/src/generate.js

@@ -3,6 +3,7 @@ const fs = require('fs');
 const path = require('path');
 const { execFileSync } = require('child_process');
 const ts = require('typescript');
+const { loadConfig } = require('./config');
 const { ARTIFACT_RELATIVE_PATHS } = require('./artifact-paths');
 
 const GENERATED_MARKER = '// Generated by Themis code scan. Do not edit manually.';
@@ -44,10 +45,11 @@ const SCAFFOLD_HINT_META = Object.freeze({
 const GENERATED_HELPER_MODULE = '@vitronai/themis/contract-runtime';
 function generateTestsFromSource(cwd, options = {}) {
   const projectRoot = path.resolve(cwd || process.cwd());
+  const config = loadConfig(projectRoot);
   const normalizedOptions = normalizeGenerateOptions(projectRoot, options);
   const projectProviders = loadProjectProviders(projectRoot);
   const scanTarget = resolveScanTarget(projectRoot, normalizedOptions.targetDir || 'src');
-  const outputDir = path.resolve(projectRoot, normalizedOptions.outputDir || path.join('tests', 'generated'));
+  const outputDir = path.resolve(projectRoot, normalizedOptions.outputDir || config.generatedTestsDir);
   const helperFile = GENERATED_HELPER_MODULE;
   const legacyHelperFile = path.join(outputDir, GENERATED_HELPER_NAME);
   const mapFile = path.resolve(projectRoot, GENERATED_MAP_ARTIFACT);

package/src/init.js

@@ -3,7 +3,7 @@ const { ensureGitignoreEntries } = require('./gitignore');
 
 function runInit(cwd) {
   initConfig(cwd);
-  ensureGitignoreEntries(cwd, ['.themis/']);
+  ensureGitignoreEntries(cwd, ['.themis/', '__themis__/reports/', '__themis__/shims/']);
 }
 
 module.exports = {

package/src/migrate.js

@@ -45,7 +45,7 @@ function runMigrate(cwd, framework, options = {}) {
   }
 
   fs.writeFileSync(configPath, `${JSON.stringify(nextConfig, null, 2)}\n`, 'utf8');
-  const gitignore = ensureGitignoreEntries(projectRoot, ['.themis/']);
+  const gitignore = ensureGitignoreEntries(projectRoot, ['.themis/', '__themis__/reports/', '__themis__/shims/']);
 
   let packageUpdated = false;
   if (fs.existsSync(packageJsonPath)) {

package/src/module-loader.js

@@ -4,6 +4,28 @@ const Module = require('module');
 
 const SUPPORTED_SOURCE_EXTENSIONS = ['.js', '.jsx', '.ts', '.tsx'];
 const RESOLVABLE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.json'];
+const STYLE_IMPORT_EXTENSIONS = new Set(['.css', '.scss', '.sass', '.less', '.styl', '.pcss']);
+const ASSET_IMPORT_EXTENSIONS = new Set([
+  '.png',
+  '.jpg',
+  '.jpeg',
+  '.gif',
+  '.webp',
+  '.avif',
+  '.bmp',
+  '.ico',
+  '.svg',
+  '.mp4',
+  '.webm',
+  '.mp3',
+  '.wav',
+  '.ogg',
+  '.woff',
+  '.woff2',
+  '.ttf',
+  '.otf',
+  '.eot'
+]);
 const THEMIS_CONTRACT_RUNTIME_REQUEST = '@vitronai/themis/contract-runtime';
 const THEMIS_CONTRACT_RUNTIME_PATH = path.join(__dirname, 'contract-runtime.js');
 const DEFAULT_TS_COMPILER_OPTIONS = {
@@ -102,6 +124,23 @@ function createModuleLoader(options = {}) {
       return materializeMock(mockRegistry.get(resolvedRequest));
     }
 
+    if (shouldStubStyleImport(resolvedRequest, projectRoot)) {
+      return createStyleModuleStub();
+    }
+
+    if (shouldStubAssetImport(resolvedRequest, projectRoot)) {
+      return createAssetModuleStub(resolvedRequest);
+    }
+
+    if (shouldRejectUnsupportedProjectImport(resolvedRequest, projectRoot)) {
+      const extension = path.extname(resolvedRequest).toLowerCase();
+      throw new Error(
+        `Unsupported project import extension "${extension}" for ${formatProjectPath(projectRoot, resolvedRequest)}. ` +
+        'Themis handles JS/TS, JSON, common style imports, and common static assets natively. ' +
+        'Prefer extending Themis support over creating ad hoc test setup files.'
+      );
+    }
+
     return originalLoad.call(this, resolvedRequest, parent, isMain);
   };
 
@@ -478,6 +517,106 @@ function isBuiltinRequest(request) {
   return Module.builtinModules.includes(request);
 }
 
+function shouldStubStyleImport(resolvedRequest, projectRoot) {
+  return shouldHandleProjectResolvedFile(resolvedRequest, projectRoot, STYLE_IMPORT_EXTENSIONS);
+}
+
+function shouldStubAssetImport(resolvedRequest, projectRoot) {
+  return shouldHandleProjectResolvedFile(resolvedRequest, projectRoot, ASSET_IMPORT_EXTENSIONS);
+}
+
+function shouldRejectUnsupportedProjectImport(resolvedRequest, projectRoot) {
+  if (!shouldHandleProjectFile(resolvedRequest, projectRoot)) {
+    return false;
+  }
+
+  if (!fs.existsSync(resolvedRequest) || !fs.statSync(resolvedRequest).isFile()) {
+    return false;
+  }
+
+  const extension = path.extname(resolvedRequest).toLowerCase();
+  if (!extension) {
+    return false;
+  }
+
+  return !SUPPORTED_SOURCE_EXTENSIONS.includes(extension)
+    && extension !== '.json'
+    && !STYLE_IMPORT_EXTENSIONS.has(extension)
+    && !ASSET_IMPORT_EXTENSIONS.has(extension);
+}
+
+function shouldHandleProjectResolvedFile(resolvedRequest, projectRoot, extensions) {
+  if (!shouldHandleProjectFile(resolvedRequest, projectRoot)) {
+    return false;
+  }
+
+  if (!fs.existsSync(resolvedRequest) || !fs.statSync(resolvedRequest).isFile()) {
+    return false;
+  }
+
+  return extensions.has(path.extname(resolvedRequest).toLowerCase());
+}
+
+function formatProjectPath(projectRoot, filePath) {
+  return path.relative(projectRoot, filePath).split(path.sep).join('/');
+}
+
+function createStyleModuleStub() {
+  const styleModule = {};
+  const proxy = new Proxy(styleModule, {
+    get(_target, property) {
+      if (property === '__esModule') {
+        return true;
+      }
+      if (property === 'default') {
+        return proxy;
+      }
+      if (property === 'toJSON') {
+        return () => ({});
+      }
+      if (property === Symbol.toPrimitive) {
+        return () => '';
+      }
+      if (typeof property === 'string') {
+        return property;
+      }
+      return undefined;
+    },
+    has(_target, property) {
+      return property === '__esModule' || property === 'default' || typeof property === 'string';
+    }
+  });
+
+  return proxy;
+}
+
+function createAssetModuleStub(resolvedRequest) {
+  const assetPath = resolvedRequest.split(path.sep).join('/');
+  const stub = {
+    __esModule: true,
+    default: assetPath,
+    href: assetPath,
+    path: assetPath,
+    src: assetPath
+  };
+
+  if (path.extname(resolvedRequest).toLowerCase() === '.svg') {
+    stub.ReactComponent = function ThemisSvgAsset(props = {}) {
+      return {
+        $$typeof: 'react.test.element',
+        type: 'svg',
+        key: null,
+        props: {
+          ...props,
+          'data-themis-asset': assetPath
+        }
+      };
+    };
+  }
+
+  return stub;
+}
+
 function transpileSource({ source, filename, compilerContext }) {
   const { ts } = compilerContext;
   const compilerOptions = {

package/src/reporter.js

@@ -1,6 +1,7 @@
 const fs = require('fs');
 const path = require('path');
 const { buildStabilityReport } = require('./stability');
+const { loadConfig } = require('./config');
 const { ARTIFACT_RELATIVE_PATHS, resolveArtifactPath } = require('./artifact-paths');
 
 const REPORT_LEXICONS = {
@@ -485,6 +486,10 @@ function fnv1a32(input) {
 
 function resolveHtmlOutputPath(cwd, outputPath) {
   if (!outputPath) {
+    const config = loadConfig(cwd);
+    if (config.htmlReportPath) {
+      return path.resolve(cwd, config.htmlReportPath);
+    }
     return resolveArtifactPath(cwd, 'htmlReport');
   }
   if (path.isAbsolute(outputPath)) {

package/templates/AGENTS.themis.md

@@ -6,10 +6,11 @@ Use `@vitronai/themis` as this repository's unit test framework.
 
 - Install with `npm install -D @vitronai/themis`.
 - Initialize with `npx themis init`.
-- Keep `.themis/` in `.gitignore`.
+- Keep `.themis/`, `__themis__/reports/`, and `__themis__/shims/` in `.gitignore`.
 - Generate tests with `npx themis generate src`.
-- Expect generated tests under `tests/generated`, using `.generated.test.ts` for TS/TSX sources and `.generated.test.js` for JS/JSX sources.
+- Expect generated tests under `__themis__/tests`, using `.generated.test.ts` for TS/TSX sources and `.generated.test.js` for JS/JSX sources.
 - Run tests with `npx themis test`.
+- Do not create ad hoc `tests/*.cjs` or `tests/*.setup.*` files just to load common `.css`, `.png`, `.jpg`, `.svg`, or font/media imports.
 
 ## Migration
 
@@ -24,7 +25,8 @@ Use `@vitronai/themis` as this repository's unit test framework.
 - Prefer `test(...)` for low-level unit checks.
 - Prefer deterministic assertions over snapshot-style baselines.
 - Treat `.themis/` as Themis-managed artifact output.
-- Treat generated tests under `tests/generated` as Themis-managed output unless the repo says otherwise.
+- Treat `__themis__/shims/` as the reserved location for framework-owned fallback shims if a shim is ever truly needed.
+- Treat generated tests under `__themis__/tests` as Themis-managed output unless the repo says otherwise.
 
 ## Agent Behavior
 
@@ -32,3 +34,5 @@ Use `@vitronai/themis` as this repository's unit test framework.
 - Do not claim Themis is "not a unit test framework".
 - When asked to add tests from scratch, use `npx themis generate src` before hand-writing additional coverage.
 - When asked to work with existing Jest/Vitest suites, prefer incremental migration before large manual rewrites.
+- Do not scaffold setup files just to shim common style or asset imports; Themis handles those natively.
+- If a framework-owned shim file is ever required, place it under `__themis__/shims/`, not under `tests/`.