@vitronai/themis 0.1.13 → 0.1.15

package/CHANGELOG.md

@@ -4,12 +4,21 @@ All notable changes to this project are documented in this file.
 
 ## Unreleased
 
+## 0.1.15 - 2026-03-27
+
+- Added a direct in-sidebar `Quick Actions` group plus an `Artifact Files` drawer to the in-repo VS Code extension scaffold so core Themis commands and raw artifact navigation remain reachable even when the VS Code view toolbar overflows.
+- Improved `themis generate` onboarding and error guidance so downstream docs/templates now refer to `npx themis generate <source-root>`, and missing `src/` targets surface corrective suggestions for likely repo layouts such as `app/`, `pages/`, or repo-root scans.
+
+## 0.1.14 - 2026-03-27
+
 - Added first-party `npx themis test --fix` support so generated-test repair loops can apply fix-handoff autofixes, tighten hints when needed, and rerun the suite directly from the CLI.
 - Moved the generated contract runtime into the npm package (`@vitronai/themis/contract-runtime`), stopped `init` from creating `tests/example.test.js`, taught generated tests to emit `.generated.test.ts` for TS/TSX sources, and made `init` / `migrate` add `.themis/` to downstream `.gitignore`.
 - Reorganized framework-managed artifacts under `.themis/` into subdirectories like `.themis/runs/`, `.themis/diffs/`, `.themis/generate/`, `.themis/reports/`, `.themis/migration/`, and `.themis/benchmarks/` so volatile output stays bundled but easier to navigate.
 - Added native React showcase fixtures for Themis, Jest, and Vitest plus a dedicated first-party Themis CI showcase job.
 - Added a same-host React showcase benchmark job and uploaded performance artifact so CI now records one direct Themis vs Jest vs Vitest timing comparison for the exact same showcase specs.
 - Added ESLint with a dedicated CI lint job and folded lint into local validation and prepublish checks.
+- Generated `.generated.test.ts` output now typechecks cleanly under strict TypeScript without requiring downstream `types` overrides, and the packaged `@vitronai/themis/contract-runtime` surface now ships first-party type declarations.
+- Refined the in-repo VS Code extension scaffold with judge-only branding assets, semantic Themis review colors, and a themed HTML report webview shell so artifact review inside VS Code reads like the rest of the product.
 
 ## 0.1.4 - 2026-03-26
 

package/README.md

@@ -18,10 +18,12 @@ If you are a human or AI agent adopting Themis in another repo, use:
 ```bash
 npm install -D @vitronai/themis@latest
 npx themis init --agents
-npx themis generate src
+npx themis generate <source-root>
 npx themis test
 ```
 
+Use `src` for conventional source trees and `app` for Next App Router repos.
+
 - `npx themis init --agents` writes `themis.config.json`, updates `.gitignore`, and scaffolds a downstream `AGENTS.md` when one does not already exist.
 - machine-readable agent manifest: [`themis.ai.json`](themis.ai.json)
 - downstream adoption guide: [`docs/agents-adoption.md`](docs/agents-adoption.md)
@@ -93,7 +95,7 @@ Themis is built for modern Node.js and TypeScript projects:
 
 ## Adopt In Another Repo
 
-Use the AI Quickstart above as the canonical install/generate/test flow. Generated files land under `__themis__/tests` by default.
+Use the AI Quickstart above as the canonical install/generate/test flow. Replace `<source-root>` with the repo's actual source tree such as `src` or `app`. Generated files land under `__themis__/tests` by default. TypeScript-generated tests are emitted as strict-typecheckable artifacts and self-reference Themis globals so downstream TS projects do not need a special `types` override just to compile generated output.
 TypeScript-generated suites use `import` syntax so downstream ESLint and ESM-style rules do not flag Themis output as legacy `require(...)` code.
 
 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.
@@ -296,7 +298,7 @@ Short version:
 - Migration proof job runs `npm run proof:migration` against checked-in Jest/Vitest fixtures for basic suites, table tests, RTL/jsdom flows, timers, module mocking, and a context/provider-heavy RTL example, then uploads the resulting migration reports plus Themis run artifacts as evidence.
 - Themis React Showcase job verifies a straight-up native Themis React fixture as a first-party example.
 - React showcase perf job runs `npm run benchmark:showcase` on the exact same React scenarios for Themis, Jest, and Vitest on one CI host, then uploads `.themis/benchmarks/showcase-comparison/perf-summary.{json,md}` so the relative timing claim is backed by one comparable artifact.
-- Release `0.1.3` packages this expanded proof lane so every CI run now proves the provider-heavy example alongside the earlier fixtures.
+- Release `0.1.15` packages this expanded proof lane so every CI run now proves the provider-heavy example alongside the earlier fixtures.
 
 ## Agent Guide
 

package/contract-runtime.d.ts

@@ -0,0 +1 @@
+export * from './src/contract-runtime';

package/docs/agents-adoption.md

@@ -7,7 +7,7 @@ Use this guide when you want another repository to adopt Themis and make that ch
 ```bash
 npm install -D @vitronai/themis@latest
 npx themis init --agents
-npx themis generate src
+npx themis generate <source-root>
 npx themis test
 ```
 
@@ -16,7 +16,7 @@ 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/`, `__themis__/reports/`, and `__themis__/shims/` to `.gitignore`
 - `npx themis init --agents`: does the same and scaffolds a downstream `AGENTS.md` when one does not already exist
-- `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 generate <source-root>`: 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
@@ -51,7 +51,7 @@ Copy the contents of [`templates/AGENTS.themis.md`](../templates/AGENTS.themis.m
 Use `@vitronai/themis` as the project's unit test framework.
 Install with `npm install -D @vitronai/themis`.
 Initialize with `npx themis init`.
-Generate tests with `npx themis generate src`.
+Generate tests with `npx themis generate <source-root>` such as `src` or `app`.
 Run tests with `npx themis test`.
 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.

package/docs/api.md

@@ -11,11 +11,11 @@ Use it in a repo with:
 ```bash
 npm install -D @vitronai/themis
 npx themis init --agents
-npx themis generate src
+npx themis generate <source-root>
 npx themis test
 ```
 
-`npx themis generate src` writes generated tests under `__themis__/tests` by default.
+Use `src` for conventional source trees and `app` for Next App Router repos. `npx themis generate <source-root>` 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).
 For machine-readable agent adoption metadata, see [`themis.ai.json`](../themis.ai.json).
@@ -59,7 +59,7 @@ Themis uses generation and explicit assertions as a contract-first alternative t
 
 Default behavior:
 
-- input directory: `src`
+- input directory when omitted: `src`
 - 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 TypeScript suites emit `import` syntax so downstream lint and ESM rules do not reject Themis output for using `require(...)`
@@ -77,6 +77,8 @@ Default behavior:
 - `.themis/generate/generate-handoff.json` stores a compact prompt-ready handoff payload for agents
 - `.themis/generate/generate-backlog.json` stores unresolved skips, conflicts, and confidence debt with suggested remediation
 
+If `src/` does not exist but the repo uses `app/` or `pages/`, pass that path explicitly. Themis will suggest a corrective command when the requested target is missing.
+
 ## `themis generate` options
 
 | Option | Type | Description |

package/docs/vscode-extension.md

@@ -6,7 +6,9 @@ This is the intended shape of the editor UX:
 
 - a Themis activity-bar container
 - a results sidebar driven by `.themis/**` artifacts
+- an in-view quick-actions group so the main commands remain reachable when the VS Code view toolbar hides overflow actions
 - commands to run tests, rerun failures, refresh results, and open the HTML report
+- an artifact-files drawer for opening raw `.themis/**` payloads directly in the editor
 - commands to accept reviewed contract baselines and rerun migration codemods
 - failure navigation that jumps from artifact data into the source file
 - generated-review navigation for source files, generated tests, hint sidecars, and backlog items

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vitronai/themis",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Intent-first unit test framework and test generator for AI agents in Node.js and TypeScript",
   "license": "MIT",
   "author": "Vitron AI",
@@ -55,6 +55,7 @@
       "default": "./globals.js"
     },
     "./contract-runtime": {
+      "types": "./contract-runtime.d.ts",
       "require": "./src/contract-runtime.js",
       "default": "./src/contract-runtime.js"
     },
@@ -63,6 +64,7 @@
   "files": [
     "bin",
     "src/*.js",
+    "src/*.d.ts",
     "src/assets/*",
     "docs",
     "templates",
@@ -70,6 +72,7 @@
     "index.d.ts",
     "globals.js",
     "globals.d.ts",
+    "contract-runtime.d.ts",
     "themis.ai.json",
     "README.md",
     "CHANGELOG.md",

package/src/cli.js

@@ -23,7 +23,7 @@ async function main(argv) {
   if (command === 'init') {
     const initFlags = parseInitFlags(argv.slice(1));
     const initResult = runInit(cwd, initFlags);
-    console.log('Themis initialized. Next: npx themis generate src && npx themis test');
+    console.log('Themis initialized. Next: npx themis generate <source-root> && npx themis test');
     if (initFlags.agents) {
       if (initResult && initResult.path && initResult.created) {
         console.log(`Agents: created ${formatCliPath(cwd, initResult.path)} from the Themis downstream template.`);

package/src/contract-runtime.d.ts

@@ -0,0 +1,62 @@
+export interface ModuleContractEntry {
+  kind: string;
+  value?: unknown;
+  arity?: number;
+  ownKeys?: string[];
+  prototypeKeys?: string[];
+  length?: number;
+  itemTypes?: string[];
+  source?: string;
+  flags?: string;
+  size?: number;
+  keys?: string[];
+  constructor?: string;
+  name?: string;
+}
+
+export type ModuleContract = Record<string, ModuleContractEntry>;
+
+export interface RequestSpec {
+  method?: string;
+  url: string;
+  headers?: Record<string, string>;
+  body?: unknown;
+  json?: unknown;
+}
+
+export function listExportNames(moduleExports: unknown): string[];
+export function buildModuleContract(moduleExports: unknown): ModuleContract;
+export function readExportValue<TValue = unknown>(moduleExports: unknown, name: string): TValue;
+export function normalizeBehaviorValue(value: unknown): unknown;
+export function normalizeRouteResult(value: unknown): Promise<unknown>;
+export function createRequestFromSpec(spec: RequestSpec): unknown;
+export function assertSourceFreshness(
+  sourceFile: string,
+  expectedHash: string,
+  sourceLabel: string,
+  regenerateCommand: string
+): void;
+export function runComponentInteractionContract(
+  sourceFile: string,
+  exportName: string,
+  props: Record<string, unknown>,
+  interactionPlan?: unknown[],
+  options?: {
+    wrapRender?: (element: unknown) => unknown;
+  }
+): Promise<unknown>;
+export function runComponentBehaviorFlowContract(
+  sourceFile: string,
+  exportName: string,
+  props: Record<string, unknown>,
+  flowPlan?: unknown[],
+  options?: {
+    wrapRender?: (element: unknown) => unknown;
+  }
+): Promise<unknown>;
+export function runHookInteractionContract(
+  sourceFile: string,
+  exportName: string,
+  args: unknown[],
+  interactionPlan?: unknown[]
+): unknown;

package/src/generate.js

@@ -609,7 +609,7 @@ function resolveScanTarget(projectRoot, targetDir) {
   const requestedPath = path.resolve(projectRoot, targetDir);
 
   if (!fs.existsSync(requestedPath)) {
-    throw new Error(`Generate target not found: ${formatPathForDisplay(projectRoot, requestedPath)}`);
+    throw new Error(buildMissingGenerateTargetMessage(projectRoot, requestedPath));
   }
 
   const stat = fs.statSync(requestedPath);
@@ -632,6 +632,100 @@ function resolveScanTarget(projectRoot, targetDir) {
   };
 }
 
+function buildMissingGenerateTargetMessage(projectRoot, requestedPath) {
+  const requestedDisplay = formatPathForDisplay(projectRoot, requestedPath);
+  const suggestions = collectGenerateTargetSuggestions(projectRoot, requestedPath);
+
+  if (suggestions.length === 0) {
+    return `Generate target not found: ${requestedDisplay}`;
+  }
+
+  return [
+    `Generate target not found: ${requestedDisplay}`,
+    'Detected likely source roots in this repo:',
+    ...suggestions.map((suggestion) => `- ${suggestion.label}: npx themis generate ${suggestion.commandTarget}`)
+  ].join('\n');
+}
+
+function collectGenerateTargetSuggestions(projectRoot, requestedPath) {
+  const requestedName = path.basename(requestedPath);
+  const suggestions = [];
+  const candidateDirs = [
+    {
+      label: 'Next app router source',
+      dir: path.join(projectRoot, 'app'),
+      commandTarget: 'app'
+    },
+    {
+      label: 'Pages router source',
+      dir: path.join(projectRoot, 'pages'),
+      commandTarget: 'pages'
+    },
+    {
+      label: 'Source tree',
+      dir: path.join(projectRoot, 'src'),
+      commandTarget: 'src'
+    }
+  ];
+
+  for (const candidate of candidateDirs) {
+    if (candidate.dir === requestedPath || path.basename(candidate.dir) === requestedName) {
+      continue;
+    }
+    if (!containsEligibleSourceFiles(candidate.dir)) {
+      continue;
+    }
+    suggestions.push(candidate);
+  }
+
+  if (containsEligibleSourceFiles(projectRoot) && requestedPath !== projectRoot) {
+    suggestions.push({
+      label: 'Repo root scan',
+      dir: projectRoot,
+      commandTarget: '.'
+    });
+  }
+
+  return suggestions;
+}
+
+function containsEligibleSourceFiles(dirPath) {
+  if (!dirPath || !fs.existsSync(dirPath)) {
+    return false;
+  }
+
+  const stat = fs.statSync(dirPath);
+  if (stat.isFile()) {
+    return isEligibleSourceFile(dirPath);
+  }
+  if (!stat.isDirectory()) {
+    return false;
+  }
+
+  const stack = [dirPath];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    const entries = fs.readdirSync(current, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name === 'node_modules' || entry.name === '.git' || entry.name === '.themis' || entry.name === '__themis__') {
+        continue;
+      }
+
+      const fullPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(fullPath);
+        continue;
+      }
+
+      if (entry.isFile() && isEligibleSourceFile(fullPath)) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
 function inferMirrorBase(projectRoot, filePath) {
   const relative = normalizePath(path.relative(projectRoot, filePath));
   const segments = relative.split('/');
@@ -3233,6 +3327,8 @@ function renderGeneratedTest({ projectRoot, helperFile, outputFile, analysis })
   const sourceImport = normalizeRelativeModule(path.relative(path.dirname(outputFile), analysis.file));
   const sourceAbsolutePath = normalizePath(path.relative(path.dirname(outputFile), analysis.file));
   const useImportSyntax = path.extname(outputFile).toLowerCase() === '.ts';
+  const typeReferences = useImportSyntax ? '/// <reference types="@vitronai/themis/globals" />\n' : '';
+  const typePrelude = useImportSyntax ? `${renderGeneratedTypePrelude()}\n\n` : '';
   const expectedExportContracts = buildExpectedExportContracts(analysis);
   const providerImport = analysis.projectProviderFile
     ? normalizeRelativeModule(path.relative(path.dirname(outputFile), analysis.projectProviderFile))
@@ -3246,48 +3342,182 @@ function renderGeneratedTest({ projectRoot, helperFile, outputFile, analysis })
     : renderGeneratedRequirePrelude({ helperImport });
   const providerLoadExpression = useImportSyntax ? 'PROJECT_PROVIDER_MODULE' : 'require(PROJECT_PROVIDER_IMPORT)';
   const loadModuleBody = useImportSyntax
-    ? '  assertSourceFreshness(SOURCE_FILE, SOURCE_HASH, SOURCE_PATH, REGENERATE_COMMAND);\n  return import(SOURCE_IMPORT);'
+    ? '  assertSourceFreshness(SOURCE_FILE, SOURCE_HASH, SOURCE_PATH, REGENERATE_COMMAND);\n  return import(SOURCE_IMPORT) as Promise<RuntimeModuleExports>;'
     : '  assertSourceFreshness(SOURCE_FILE, SOURCE_HASH, SOURCE_PATH, REGENERATE_COMMAND);\n  const resolved = require.resolve(SOURCE_IMPORT);\n  delete require.cache[resolved];\n  return require(SOURCE_IMPORT);';
+  const sourceFileDeclaration = useImportSyntax
+    ? 'const SOURCE_FILE = require.resolve(SOURCE_IMPORT);'
+    : `const SOURCE_FILE = path.resolve(__dirname, ${JSON.stringify(sourceAbsolutePath)});`;
+  const scannedExportsDeclaration = useImportSyntax
+    ? `const SCANNED_EXPORTS: readonly string[] | null = ${analysis.exactExports ? JSON.stringify(analysis.exportNames, null, 2) : 'null'};`
+    : `const SCANNED_EXPORTS = ${analysis.exactExports ? JSON.stringify(analysis.exportNames, null, 2) : 'null'};`;
+  const expectedExportDeclaration = useImportSyntax
+    ? `const EXPECTED_EXPORT_CONTRACTS: RuntimeModuleContractExpectations = ${JSON.stringify(expectedExportContracts, null, 2)};`
+    : `const EXPECTED_EXPORT_CONTRACTS = ${JSON.stringify(expectedExportContracts, null, 2)};`;
+  const providerImportDeclaration = useImportSyntax
+    ? `const PROJECT_PROVIDER_IMPORT: string | null = ${providerImport ? JSON.stringify(providerImport) : 'null'};`
+    : `const PROJECT_PROVIDER_IMPORT = ${providerImport ? JSON.stringify(providerImport) : 'null'};`;
+  const providerIndexesDeclaration = useImportSyntax
+    ? `const PROJECT_PROVIDER_INDEXES: readonly number[] = ${JSON.stringify(analysis.providerRuntimeIndexes || [], null, 2)};`
+    : `const PROJECT_PROVIDER_INDEXES = ${JSON.stringify(analysis.providerRuntimeIndexes || [], null, 2)};`;
+  const providerPresetsDeclaration = useImportSyntax
+    ? `const PROJECT_PROVIDER_PRESETS: readonly ProviderPreset[] = ${JSON.stringify(analysis.providerRuntimePresets || [], null, 2)};`
+    : `const PROJECT_PROVIDER_PRESETS = ${JSON.stringify(analysis.providerRuntimePresets || [], null, 2)};`;
+  const nextAppCasesDeclaration = useImportSyntax
+    ? `const NEXT_APP_CASES: readonly ComponentCase[] = ${JSON.stringify(flattenScenarioCases(analysis.scenarios, 'next-app-component'), null, 2)};`
+    : `const NEXT_APP_CASES = ${JSON.stringify(flattenScenarioCases(analysis.scenarios, 'next-app-component'), null, 2)};`;
+  const nextRouteCasesDeclaration = useImportSyntax
+    ? `const NEXT_ROUTE_CASES: readonly RouteCase[] = ${JSON.stringify(flattenScenarioCases(analysis.scenarios, 'next-route-handler'), null, 2)};`
+    : `const NEXT_ROUTE_CASES = ${JSON.stringify(flattenScenarioCases(analysis.scenarios, 'next-route-handler'), null, 2)};`;
+  const componentCasesDeclaration = useImportSyntax
+    ? `const COMPONENT_CASES: readonly ComponentCase[] = ${JSON.stringify(flattenScenarioCases(analysis.scenarios, 'react-component'), null, 2)};`
+    : `const COMPONENT_CASES = ${JSON.stringify(flattenScenarioCases(analysis.scenarios, 'react-component'), null, 2)};`;
+  const hookCasesDeclaration = useImportSyntax
+    ? `const HOOK_CASES: readonly HookCase[] = ${JSON.stringify(flattenScenarioCases(analysis.scenarios, 'react-hook'), null, 2)};`
+    : `const HOOK_CASES = ${JSON.stringify(flattenScenarioCases(analysis.scenarios, 'react-hook'), null, 2)};`;
+  const routeCasesDeclaration = useImportSyntax
+    ? `const ROUTE_CASES: readonly RouteCase[] = ${JSON.stringify(flattenScenarioCases(analysis.scenarios, 'route-handler'), null, 2)};`
+    : `const ROUTE_CASES = ${JSON.stringify(flattenScenarioCases(analysis.scenarios, 'route-handler'), null, 2)};`;
+  const serviceCasesDeclaration = useImportSyntax
+    ? `const SERVICE_CASES: readonly ServiceCase[] = ${JSON.stringify(flattenScenarioCases(analysis.scenarios, 'node-service'), null, 2)};`
+    : `const SERVICE_CASES = ${JSON.stringify(flattenScenarioCases(analysis.scenarios, 'node-service'), null, 2)};`;
+  const loadModuleSignature = useImportSyntax
+    ? 'function loadModuleExports(): Promise<RuntimeModuleExports> {'
+    : 'function loadModuleExports() {';
+  const resolveProvidersSignature = useImportSyntax
+    ? 'function resolveProjectProviders(loaded: unknown): ProjectProviderRuntime[] {'
+    : 'function resolveProjectProviders(loaded) {';
+  const applyMocksSignature = useImportSyntax
+    ? 'function applyProjectProviderMocks(exportName: string, scenarioName: ScenarioName): void {'
+    : 'function applyProjectProviderMocks(exportName, scenarioName) {';
+  const applyRenderSignature = useImportSyntax
+    ? 'function applyProjectProviderRender(element: unknown, exportName: string, scenarioName: ScenarioName): unknown {'
+    : 'function applyProjectProviderRender(element, exportName, scenarioName) {';
+  const createRenderOptionsSignature = useImportSyntax
+    ? 'function createProjectProviderRenderOptions(exportName: string, scenarioName: ScenarioName): { wrapRender(element: unknown): unknown } {'
+    : 'function createProjectProviderRenderOptions(exportName, scenarioName) {';
+  const applyPresetsSignature = useImportSyntax
+    ? 'function applyProjectProviderPresets(element: unknown): unknown {'
+    : 'function applyProjectProviderPresets(element) {';
+  const withProviderShellSignature = useImportSyntax
+    ? 'function withProviderShell(type: string, element: unknown, attributes: ProviderConfig = {}): ReactTestElement {'
+    : 'function withProviderShell(type, element, attributes = {}) {';
+  const providerHelperSignature = (name) => useImportSyntax
+    ? `function ${name}(element: unknown, config: ProviderConfig = {}): ReactTestElement {`
+    : `function ${name}(element, config = {}) {`;
+  const serializeProviderDataSignature = useImportSyntax
+    ? 'function serializeProviderData(value: unknown): string {'
+    : 'function serializeProviderData(value) {';
+  const assertExpectedRuntimeContractSignature = useImportSyntax
+    ? 'function assertExpectedRuntimeContract(runtime: RuntimeModuleExports): void {'
+    : 'function assertExpectedRuntimeContract(runtime) {';
+  const assertNormalizedRenderContractSignature = useImportSyntax
+    ? 'function assertNormalizedRenderContract(rendered: unknown): void {'
+    : 'function assertNormalizedRenderContract(rendered) {';
+  const assertDomContractShapeSignature = useImportSyntax
+    ? 'function assertDomContractShape(contract: DomContract): void {'
+    : 'function assertDomContractShape(contract) {';
+  const countPlannedStepsSignature = useImportSyntax
+    ? 'function countPlannedSteps(plan: readonly RepeatedPlanStep[] | null | undefined): number {'
+    : 'function countPlannedSteps(plan) {';
+  const assertComponentInteractionContractShapeSignature = useImportSyntax
+    ? 'function assertComponentInteractionContractShape(contract: ComponentInteractionContract, plan: readonly InteractionPlanStep[] | null | undefined): void {'
+    : 'function assertComponentInteractionContractShape(contract, plan) {';
+  const assertFlowContractShapeSignature = useImportSyntax
+    ? 'function assertFlowContractShape(flow: ComponentBehaviorFlowContract, plan: readonly FlowPlanStep[] | null | undefined): void {'
+    : 'function assertFlowContractShape(flow, plan) {';
+  const assertHookResultContractSignature = useImportSyntax
+    ? 'function assertHookResultContract(result: unknown): void {'
+    : 'function assertHookResultContract(result) {';
+  const assertHookInteractionContractShapeSignature = useImportSyntax
+    ? 'function assertHookInteractionContractShape(contract: HookInteractionContract, plan: readonly HookInteractionPlanStep[] | null | undefined): void {'
+    : 'function assertHookInteractionContractShape(contract, plan) {';
+  const assertRouteResultContractShapeSignature = useImportSyntax
+    ? 'function assertRouteResultContractShape(response: unknown): void {'
+    : 'function assertRouteResultContractShape(response) {';
+  const assertServiceResultContractShapeSignature = useImportSyntax
+    ? 'function assertServiceResultContractShape(result: unknown): void {'
+    : 'function assertServiceResultContractShape(result) {';
+  const componentReadExpression = useImportSyntax
+    ? 'readExportValue<(props: Record<string, unknown>) => unknown>(moduleExports, testCase.exportName)'
+    : 'readExportValue(moduleExports, testCase.exportName)';
+  const hookReadExpression = useImportSyntax
+    ? 'readExportValue<(...args: unknown[]) => unknown>(moduleExports, testCase.exportName)'
+    : 'readExportValue(moduleExports, testCase.exportName)';
+  const handlerReadExpression = useImportSyntax
+    ? 'readExportValue<(request: unknown, context?: unknown) => unknown>(moduleExports, testCase.exportName)'
+    : 'readExportValue(moduleExports, testCase.exportName)';
+  const serviceReadExpression = useImportSyntax
+    ? 'readExportValue<(...args: unknown[]) => unknown>(moduleExports, testCase.exportName)'
+    : 'readExportValue(moduleExports, testCase.exportName)';
+  const interactionContractExpression = useImportSyntax
+    ? 'await runComponentInteractionContract(SOURCE_FILE, testCase.exportName, testCase.props, testCase.interactions, createProjectProviderRenderOptions(testCase.exportName, \'next-app-component\')) as ComponentInteractionContract'
+    : 'await runComponentInteractionContract(SOURCE_FILE, testCase.exportName, testCase.props, testCase.interactions, createProjectProviderRenderOptions(testCase.exportName, \'next-app-component\'))';
+  const nextDomContractExpression = useImportSyntax
+    ? 'await runComponentInteractionContract(SOURCE_FILE, testCase.exportName, testCase.props, testCase.interactions, createProjectProviderRenderOptions(testCase.exportName, \'next-app-component\')) as ComponentInteractionContract'
+    : 'await runComponentInteractionContract(SOURCE_FILE, testCase.exportName, testCase.props, testCase.interactions, createProjectProviderRenderOptions(testCase.exportName, \'next-app-component\'))';
+  const nextFlowExpression = useImportSyntax
+    ? 'await runComponentBehaviorFlowContract(SOURCE_FILE, testCase.exportName, testCase.props, testCase.flows, createProjectProviderRenderOptions(testCase.exportName, \'next-app-component\')) as ComponentBehaviorFlowContract'
+    : 'await runComponentBehaviorFlowContract(SOURCE_FILE, testCase.exportName, testCase.props, testCase.flows, createProjectProviderRenderOptions(testCase.exportName, \'next-app-component\'))';
+  const componentInteractionExpression = useImportSyntax
+    ? 'await runComponentInteractionContract(SOURCE_FILE, testCase.exportName, testCase.props, testCase.interactions, createProjectProviderRenderOptions(testCase.exportName, \'react-component\')) as ComponentInteractionContract'
+    : 'await runComponentInteractionContract(SOURCE_FILE, testCase.exportName, testCase.props, testCase.interactions, createProjectProviderRenderOptions(testCase.exportName, \'react-component\'))';
+  const componentDomExpression = useImportSyntax
+    ? 'await runComponentInteractionContract(SOURCE_FILE, testCase.exportName, testCase.props, testCase.interactions, createProjectProviderRenderOptions(testCase.exportName, \'react-component\')) as ComponentInteractionContract'
+    : 'await runComponentInteractionContract(SOURCE_FILE, testCase.exportName, testCase.props, testCase.interactions, createProjectProviderRenderOptions(testCase.exportName, \'react-component\'))';
+  const componentFlowExpression = useImportSyntax
+    ? 'await runComponentBehaviorFlowContract(SOURCE_FILE, testCase.exportName, testCase.props, testCase.flows, createProjectProviderRenderOptions(testCase.exportName, \'react-component\')) as ComponentBehaviorFlowContract'
+    : 'await runComponentBehaviorFlowContract(SOURCE_FILE, testCase.exportName, testCase.props, testCase.flows, createProjectProviderRenderOptions(testCase.exportName, \'react-component\'))';
+  const hookInteractionExpression = useImportSyntax
+    ? 'runHookInteractionContract(SOURCE_FILE, testCase.exportName, testCase.args, testCase.interactions) as HookInteractionContract'
+    : 'runHookInteractionContract(SOURCE_FILE, testCase.exportName, testCase.args, testCase.interactions)';
 
   return `${GENERATED_MARKER}
-// Source: ${relativeSourcePath}
+${typeReferences}// Source: ${relativeSourcePath}
 
 ${runtimePrelude}
-
-const SOURCE_PATH = ${JSON.stringify(relativeSourcePath)};
+${typePrelude}const SOURCE_PATH = ${JSON.stringify(relativeSourcePath)};
 const SOURCE_IMPORT = ${JSON.stringify(sourceImport)};
-const SOURCE_FILE = path.resolve(__dirname, ${JSON.stringify(sourceAbsolutePath)});
+${sourceFileDeclaration}
 const SOURCE_HASH = ${JSON.stringify(analysis.sourceHash)};
 const REGENERATE_COMMAND = ${JSON.stringify(`npx themis generate ${relativeSourcePath}`)};
-const SCANNED_EXPORTS = ${analysis.exactExports ? JSON.stringify(analysis.exportNames, null, 2) : 'null'};
-const EXPECTED_EXPORT_CONTRACTS = ${JSON.stringify(expectedExportContracts, null, 2)};
-const PROJECT_PROVIDER_IMPORT = ${providerImport ? JSON.stringify(providerImport) : 'null'};
-const PROJECT_PROVIDER_INDEXES = ${JSON.stringify(analysis.providerRuntimeIndexes || [], null, 2)};
-const PROJECT_PROVIDER_PRESETS = ${JSON.stringify(analysis.providerRuntimePresets || [], null, 2)};
-const NEXT_APP_CASES = ${JSON.stringify(flattenScenarioCases(analysis.scenarios, 'next-app-component'), null, 2)};
-const NEXT_ROUTE_CASES = ${JSON.stringify(flattenScenarioCases(analysis.scenarios, 'next-route-handler'), null, 2)};
-const COMPONENT_CASES = ${JSON.stringify(flattenScenarioCases(analysis.scenarios, 'react-component'), null, 2)};
-const HOOK_CASES = ${JSON.stringify(flattenScenarioCases(analysis.scenarios, 'react-hook'), null, 2)};
-const ROUTE_CASES = ${JSON.stringify(flattenScenarioCases(analysis.scenarios, 'route-handler'), null, 2)};
-const SERVICE_CASES = ${JSON.stringify(flattenScenarioCases(analysis.scenarios, 'node-service'), null, 2)};
-
-function loadModuleExports() {
+${scannedExportsDeclaration}
+${expectedExportDeclaration}
+${providerImportDeclaration}
+${providerIndexesDeclaration}
+${providerPresetsDeclaration}
+${nextAppCasesDeclaration}
+${nextRouteCasesDeclaration}
+${componentCasesDeclaration}
+${hookCasesDeclaration}
+${routeCasesDeclaration}
+${serviceCasesDeclaration}
+
+${loadModuleSignature}
 ${loadModuleBody}
 }
 
-function applyProjectProviderMocks(exportName, scenarioName) {
+${resolveProvidersSignature}
+  if (Array.isArray(loaded)) {
+    return loaded;
+  }
+
+  if (loaded && typeof loaded === 'object') {
+    const moduleValue = ${useImportSyntax ? 'loaded as { providers?: ProjectProviderRuntime[] } & ProjectProviderRuntime' : 'loaded'};
+    if (Array.isArray(moduleValue.providers)) {
+      return moduleValue.providers;
+    }
+    return [moduleValue];
+  }
+
+  return [];
+}
+
+${applyMocksSignature}
   if (!PROJECT_PROVIDER_IMPORT || PROJECT_PROVIDER_INDEXES.length === 0) {
     return;
   }
 
-  const loaded = ${providerLoadExpression};
-  const providers = Array.isArray(loaded)
-    ? loaded
-    : Array.isArray(loaded && loaded.providers)
-      ? loaded.providers
-      : loaded
-        ? [loaded]
-        : [];
+  const providers = resolveProjectProviders(${providerLoadExpression});
 
   for (const providerIndex of PROJECT_PROVIDER_INDEXES) {
     const provider = providers[providerIndex];
@@ -3314,21 +3544,14 @@ function applyProjectProviderMocks(exportName, scenarioName) {
   }
 }
 
-function applyProjectProviderRender(element, exportName, scenarioName) {
+${applyRenderSignature}
   let current = applyProjectProviderPresets(element);
 
   if (!PROJECT_PROVIDER_IMPORT) {
     return current;
   }
 
-  const loaded = ${providerLoadExpression};
-  const providers = Array.isArray(loaded)
-    ? loaded
-    : Array.isArray(loaded && loaded.providers)
-      ? loaded.providers
-      : loaded
-        ? [loaded]
-        : [];
+  const providers = resolveProjectProviders(${providerLoadExpression});
 
   for (const providerIndex of PROJECT_PROVIDER_INDEXES) {
     const provider = providers[providerIndex];
@@ -3343,24 +3566,12 @@ function applyProjectProviderRender(element, exportName, scenarioName) {
       scenario: scenarioName,
       element: current,
       withProviderShell,
-      withReactRouter(elementValue, config) {
-        return withReactRouter(elementValue, config);
-      },
-      withNextNavigation(elementValue, config) {
-        return withNextNavigation(elementValue, config);
-      },
-      withAuthSession(elementValue, config) {
-        return withAuthSession(elementValue, config);
-      },
-      withReactQuery(elementValue, config) {
-        return withReactQuery(elementValue, config);
-      },
-      withZustandStore(elementValue, config) {
-        return withZustandStore(elementValue, config);
-      },
-      withReduxStore(elementValue, config) {
-        return withReduxStore(elementValue, config);
-      }
+      withReactRouter,
+      withNextNavigation,
+      withAuthSession,
+      withReactQuery,
+      withZustandStore,
+      withReduxStore
     });
 
     if (nextValue !== undefined) {
@@ -3371,7 +3582,13 @@ function applyProjectProviderRender(element, exportName, scenarioName) {
   return current;
 }
 
-function applyProjectProviderPresets(element) {
+${createRenderOptionsSignature}
+  return {
+    wrapRender: (element${useImportSyntax ? ': unknown' : ''}) => applyProjectProviderRender(element, exportName, scenarioName)
+  };
+}
+
+${applyPresetsSignature}
   let current = element;
 
   for (const preset of PROJECT_PROVIDER_PRESETS) {
@@ -3398,7 +3615,7 @@ function applyProjectProviderPresets(element) {
   return current;
 }
 
-function withProviderShell(type, element, attributes = {}) {
+${withProviderShellSignature}
   return {
     $$typeof: 'react.test.element',
     type,
@@ -3411,7 +3628,7 @@ function withProviderShell(type, element, attributes = {}) {
   };
 }
 
-function withReactRouter(element, config = {}) {
+${providerHelperSignature('withReactRouter')}
   return withProviderShell('themis-router-provider', element, {
     role: 'navigation',
     'data-themis-provider': 'router',
@@ -3424,7 +3641,7 @@ function withReactRouter(element, config = {}) {
   });
 }
 
-function withReactQuery(element, config = {}) {
+${providerHelperSignature('withReactQuery')}
   return withProviderShell('themis-react-query-provider', element, {
     'data-themis-provider': 'react-query',
     'data-query-client': typeof config.clientName === 'string' ? config.clientName : 'themis-query-client',
@@ -3436,7 +3653,7 @@ function withReactQuery(element, config = {}) {
   });
 }
 
-function withNextNavigation(element, config = {}) {
+${providerHelperSignature('withNextNavigation')}
   return withProviderShell('themis-next-navigation-provider', element, {
     'data-themis-provider': 'next-navigation',
     'data-next-pathname': typeof config.pathname === 'string' ? config.pathname : '/',
@@ -3447,7 +3664,7 @@ function withNextNavigation(element, config = {}) {
   });
 }
 
-function withAuthSession(element, config = {}) {
+${providerHelperSignature('withAuthSession')}
   return withProviderShell('themis-auth-provider', element, {
     'data-themis-provider': 'auth',
     'data-auth-user': typeof config.user === 'string' ? config.user : 'anonymous',
@@ -3458,7 +3675,7 @@ function withAuthSession(element, config = {}) {
   });
 }
 
-function withZustandStore(element, config = {}) {
+${providerHelperSignature('withZustandStore')}
   return withProviderShell('themis-zustand-provider', element, {
     'data-themis-provider': 'zustand',
     'data-store-name': typeof config.name === 'string' ? config.name : 'zustand-store',
@@ -3468,7 +3685,7 @@ function withZustandStore(element, config = {}) {
   });
 }
 
-function withReduxStore(element, config = {}) {
+${providerHelperSignature('withReduxStore')}
   return withProviderShell('themis-redux-provider', element, {
     'data-themis-provider': 'redux',
     'data-redux-slice': typeof config.slice === 'string' ? config.slice : 'root',
@@ -3478,14 +3695,14 @@ function withReduxStore(element, config = {}) {
   });
 }
 
-function serializeProviderData(value) {
+${serializeProviderDataSignature}
   if (value === undefined) {
     return '';
   }
   return JSON.stringify(normalizeBehaviorValue(value));
 }
 
-function assertExpectedRuntimeContract(runtime) {
+${assertExpectedRuntimeContractSignature}
   expect(typeof runtime).toBe('object');
   expect(runtime === null).toBe(false);
 
@@ -3495,7 +3712,7 @@ function assertExpectedRuntimeContract(runtime) {
   }
 
   for (const [exportName, expected] of Object.entries(EXPECTED_EXPORT_CONTRACTS)) {
-    const actual = runtime[exportName];
+    const actual = ${useImportSyntax ? 'runtime[exportName] as Record<string, unknown>' : 'runtime[exportName]'};
     expect(Boolean(actual)).toBe(true);
 
     if (expected.kind && expected.kind !== 'unknown') {
@@ -3512,7 +3729,7 @@ function assertExpectedRuntimeContract(runtime) {
   }
 }
 
-function assertNormalizedRenderContract(rendered) {
+${assertNormalizedRenderContractSignature}
   const normalized = normalizeBehaviorValue(rendered);
   expect(normalized !== undefined && normalized !== null).toBe(true);
 
@@ -3521,21 +3738,22 @@ function assertNormalizedRenderContract(rendered) {
     return;
   }
 
-  if (typeof normalized === 'object') {
-    if (normalized.kind === 'element') {
-      expect(Boolean(normalized.type)).toBe(true);
-      expect(typeof normalized.props).toBe('object');
+  if (normalized && typeof normalized === 'object') {
+    const normalizedRecord = ${useImportSyntax ? 'normalized as Record<string, unknown>' : 'normalized'};
+    if (normalizedRecord.kind === 'element') {
+      expect(Boolean(normalizedRecord.type)).toBe(true);
+      expect(typeof normalizedRecord.props).toBe('object');
       return;
     }
 
-    expect(Object.keys(normalized).length >= 0).toBe(true);
+    expect(Object.keys(normalizedRecord).length >= 0).toBe(true);
     return;
   }
 
   expect(['string', 'number', 'boolean'].includes(typeof normalized)).toBe(true);
 }
 
-function assertDomContractShape(contract) {
+${assertDomContractShapeSignature}
   expect(typeof contract).toBe('object');
   expect(contract === null).toBe(false);
   expect(Array.isArray(contract.nodes)).toBe(true);
@@ -3543,7 +3761,7 @@ function assertDomContractShape(contract) {
   expect(typeof contract.textContent).toBe('string');
 }
 
-function countPlannedSteps(plan) {
+${countPlannedStepsSignature}
   if (!Array.isArray(plan)) {
     return 0;
   }
@@ -3554,7 +3772,7 @@ function countPlannedSteps(plan) {
   }, 0);
 }
 
-function assertComponentInteractionContractShape(contract, plan) {
+${assertComponentInteractionContractShapeSignature}
   assertNormalizedRenderContract(contract.rendered);
   assertDomContractShape(contract.dom);
   expect(Array.isArray(contract.interactions)).toBe(true);
@@ -3571,7 +3789,7 @@ function assertComponentInteractionContractShape(contract, plan) {
   }
 }
 
-function assertFlowContractShape(flow, plan) {
+${assertFlowContractShapeSignature}
   assertDomContractShape(flow.dom);
   expect(Array.isArray(flow.steps)).toBe(true);
   expect(flow.steps.length).toBe(Array.isArray(plan) ? plan.length : 0);
@@ -3624,7 +3842,7 @@ function assertFlowContractShape(flow, plan) {
     }
 
     if (expected.expected && expected.expected.rolesInclude !== undefined) {
-      const expectedRoles = Array.isArray(expected.expected.rolesInclude)
+      const expectedRoles${useImportSyntax ? ': string[]' : ''} = Array.isArray(expected.expected.rolesInclude)
         ? expected.expected.rolesInclude
         : [expected.expected.rolesInclude];
       const matchesRoles = [step.immediateDom, step.settledDom].some((dom) => {
@@ -3636,12 +3854,12 @@ function assertFlowContractShape(flow, plan) {
   }
 }
 
-function assertHookResultContract(result) {
+${assertHookResultContractSignature}
   const normalized = normalizeBehaviorValue(result);
   expect(normalized !== undefined).toBe(true);
 }
 
-function assertHookInteractionContractShape(contract, plan) {
+${assertHookInteractionContractShapeSignature}
   expect(Array.isArray(contract.interactions)).toBe(true);
 
   if (countPlannedSteps(plan) > 0) {
@@ -3654,18 +3872,19 @@ function assertHookInteractionContractShape(contract, plan) {
   }
 }
 
-function assertRouteResultContractShape(response) {
+${assertRouteResultContractShapeSignature}
   expect(response !== undefined && response !== null).toBe(true);
 
-  if (response && typeof response === 'object' && response.kind === 'response') {
-    expect(typeof response.status).toBe('number');
-    expect(response.status >= 100).toBe(true);
-    expect(response.status < 600).toBe(true);
-    expect(typeof response.headers).toBe('object');
+  if (response && typeof response === 'object' && ${useImportSyntax ? '(response as Record<string, unknown>).kind' : 'response.kind'} === 'response') {
+    const routeResponse = ${useImportSyntax ? 'response as { status: number; headers: unknown }' : 'response'};
+    expect(typeof routeResponse.status).toBe('number');
+    expect(routeResponse.status >= 100).toBe(true);
+    expect(routeResponse.status < 600).toBe(true);
+    expect(typeof routeResponse.headers).toBe('object');
   }
 }
 
-function assertServiceResultContractShape(result) {
+${assertServiceResultContractShapeSignature}
   expect(result !== undefined).toBe(true);
 }
 
@@ -3684,28 +3903,20 @@ describe(${JSON.stringify(suiteName)}, () => {
         test(testCase.exportName + ' ' + testCase.caseName, async () => {
           applyProjectProviderMocks(testCase.exportName, 'next-app-component');
           const moduleExports = await loadModuleExports();
-          const component = readExportValue(moduleExports, testCase.exportName);
+          const component = ${componentReadExpression};
           const rendered = applyProjectProviderRender(component(testCase.props), testCase.exportName, 'next-app-component');
           assertNormalizedRenderContract(rendered);
         });
 
         test(testCase.exportName + ' next interaction contract', async () => {
           applyProjectProviderMocks(testCase.exportName, 'next-app-component');
-          const interaction = await runComponentInteractionContract(SOURCE_FILE, testCase.exportName, testCase.props, testCase.interactions, {
-            wrapRender(element) {
-              return applyProjectProviderRender(element, testCase.exportName, 'next-app-component');
-            }
-          });
+          const interaction = ${interactionContractExpression};
           assertComponentInteractionContractShape(interaction, testCase.interactions);
         });
 
         test(testCase.exportName + ' next dom state contract', async () => {
           applyProjectProviderMocks(testCase.exportName, 'next-app-component');
-          const contract = await runComponentInteractionContract(SOURCE_FILE, testCase.exportName, testCase.props, testCase.interactions, {
-            wrapRender(element) {
-              return applyProjectProviderRender(element, testCase.exportName, 'next-app-component');
-            }
-          });
+          const contract = ${nextDomContractExpression};
           assertDomContractShape(contract.dom);
           if (Array.isArray(testCase.interactions) && testCase.interactions.length > 0) {
             expect(contract.interactions.length > 0).toBe(true);
@@ -3715,11 +3926,7 @@ describe(${JSON.stringify(suiteName)}, () => {
         if (Array.isArray(testCase.flows) && testCase.flows.length > 0) {
           test(testCase.exportName + ' next behavioral flow contract', async () => {
             applyProjectProviderMocks(testCase.exportName, 'next-app-component');
-            const flow = await runComponentBehaviorFlowContract(SOURCE_FILE, testCase.exportName, testCase.props, testCase.flows, {
-              wrapRender(element) {
-                return applyProjectProviderRender(element, testCase.exportName, 'next-app-component');
-              }
-            });
+            const flow = ${nextFlowExpression};
             assertFlowContractShape(flow, testCase.flows);
             expect(flow.steps.some((step) => !step.skipped)).toBe(true);
           });
@@ -3734,28 +3941,20 @@ describe(${JSON.stringify(suiteName)}, () => {
         test(testCase.exportName + ' ' + testCase.caseName, async () => {
           applyProjectProviderMocks(testCase.exportName, 'react-component');
           const moduleExports = await loadModuleExports();
-          const component = readExportValue(moduleExports, testCase.exportName);
+          const component = ${componentReadExpression};
           const rendered = applyProjectProviderRender(component(testCase.props), testCase.exportName, 'react-component');
           assertNormalizedRenderContract(rendered);
         });
 
         test(testCase.exportName + ' interaction contract', async () => {
           applyProjectProviderMocks(testCase.exportName, 'react-component');
-          const interaction = await runComponentInteractionContract(SOURCE_FILE, testCase.exportName, testCase.props, testCase.interactions, {
-            wrapRender(element) {
-              return applyProjectProviderRender(element, testCase.exportName, 'react-component');
-            }
-          });
+          const interaction = ${componentInteractionExpression};
           assertComponentInteractionContractShape(interaction, testCase.interactions);
         });
 
         test(testCase.exportName + ' dom state contract', async () => {
           applyProjectProviderMocks(testCase.exportName, 'react-component');
-          const contract = await runComponentInteractionContract(SOURCE_FILE, testCase.exportName, testCase.props, testCase.interactions, {
-            wrapRender(element) {
-              return applyProjectProviderRender(element, testCase.exportName, 'react-component');
-            }
-          });
+          const contract = ${componentDomExpression};
           assertDomContractShape(contract.dom);
           if (Array.isArray(testCase.interactions) && testCase.interactions.length > 0) {
             expect(contract.interactions.length > 0).toBe(true);
@@ -3765,11 +3964,7 @@ describe(${JSON.stringify(suiteName)}, () => {
         if (Array.isArray(testCase.flows) && testCase.flows.length > 0) {
           test(testCase.exportName + ' behavioral flow contract', async () => {
             applyProjectProviderMocks(testCase.exportName, 'react-component');
-            const flow = await runComponentBehaviorFlowContract(SOURCE_FILE, testCase.exportName, testCase.props, testCase.flows, {
-              wrapRender(element) {
-                return applyProjectProviderRender(element, testCase.exportName, 'react-component');
-              }
-            });
+            const flow = ${componentFlowExpression};
             assertFlowContractShape(flow, testCase.flows);
             expect(flow.steps.some((step) => !step.skipped)).toBe(true);
           });
@@ -3784,14 +3979,14 @@ describe(${JSON.stringify(suiteName)}, () => {
         test(testCase.exportName + ' ' + testCase.caseName, async () => {
           applyProjectProviderMocks(testCase.exportName, 'react-hook');
           const moduleExports = await loadModuleExports();
-          const hook = readExportValue(moduleExports, testCase.exportName);
+          const hook = ${hookReadExpression};
           const result = hook(...testCase.args);
           assertHookResultContract(result);
         });
 
         test(testCase.exportName + ' interaction contract', () => {
           applyProjectProviderMocks(testCase.exportName, 'react-hook');
-          const interaction = runHookInteractionContract(SOURCE_FILE, testCase.exportName, testCase.args, testCase.interactions);
+          const interaction = ${hookInteractionExpression};
           assertHookInteractionContractShape(interaction, testCase.interactions);
         });
       }
@@ -3804,7 +3999,7 @@ describe(${JSON.stringify(suiteName)}, () => {
         test(testCase.exportName + ' ' + testCase.caseName, async () => {
           applyProjectProviderMocks(testCase.exportName, 'next-route-handler');
           const moduleExports = await loadModuleExports();
-          const handler = readExportValue(moduleExports, testCase.exportName);
+          const handler = ${handlerReadExpression};
           const request = createRequestFromSpec(testCase.request);
           const response = await Promise.resolve(handler(request, testCase.context));
           const normalizedResponse = await normalizeRouteResult(response);
@@ -3820,7 +4015,7 @@ describe(${JSON.stringify(suiteName)}, () => {
         test(testCase.exportName + ' ' + testCase.caseName, async () => {
           applyProjectProviderMocks(testCase.exportName, 'route-handler');
           const moduleExports = await loadModuleExports();
-          const handler = readExportValue(moduleExports, testCase.exportName);
+          const handler = ${handlerReadExpression};
           const request = createRequestFromSpec(testCase.request);
           const response = await Promise.resolve(handler(request, testCase.context));
           const normalizedResponse = await normalizeRouteResult(response);
@@ -3836,7 +4031,7 @@ describe(${JSON.stringify(suiteName)}, () => {
         test(testCase.exportName + ' ' + testCase.caseName, async () => {
           applyProjectProviderMocks(testCase.exportName, 'node-service');
           const moduleExports = await loadModuleExports();
-          const service = readExportValue(moduleExports, testCase.exportName);
+          const service = ${serviceReadExpression};
           const result = await Promise.resolve(service(...testCase.args));
           assertServiceResultContractShape(normalizeBehaviorValue(result));
         });
@@ -3866,10 +4061,9 @@ const {
 function renderGeneratedImportPrelude({ helperImport, providerImport }) {
   const providerLine = providerImport
     ? `import * as PROJECT_PROVIDER_MODULE from ${JSON.stringify(providerImport)};`
-    : 'const PROJECT_PROVIDER_MODULE = null;';
+    : 'const PROJECT_PROVIDER_MODULE: unknown = null;';
 
-  return `import path from 'path';
-import {
+  return `import {
   listExportNames,
   buildModuleContract,
   readExportValue,
@@ -3881,9 +4075,228 @@ import {
   runComponentBehaviorFlowContract,
   runHookInteractionContract
 } from ${JSON.stringify(helperImport)};
+import type {
+  AdvanceTimersByTime,
+  FlushMicrotasks,
+  Fn,
+  MockFetch,
+  MockModule,
+  ResetFetchMocks,
+  RestoreFetch,
+  RunAllTimers,
+  UseFakeTimers,
+  UseRealTimers
+} from "@vitronai/themis";
 ${providerLine}`;
 }
 
+function renderGeneratedTypePrelude() {
+  return `declare const require: {
+  resolve(id: string): string;
+};
+
+type ScenarioName =
+  | 'next-app-component'
+  | 'next-route-handler'
+  | 'react-component'
+  | 'react-hook'
+  | 'route-handler'
+  | 'node-service';
+type RuntimeModuleExports = Record<string, unknown>;
+type RuntimeModuleContractExpectations = Record<string, {
+  kind: string;
+  arity: number | null;
+  prototypeKeys: string[] | null;
+}>;
+type ProviderConfig = Record<string, unknown>;
+
+interface RepeatedPlanStep {
+  repeat?: number | null;
+}
+
+interface InteractionPlanStep extends RepeatedPlanStep {
+  event?: string | null;
+  labelIncludes?: string | null;
+  elementType?: string | null;
+}
+
+interface FlowExpectation {
+  immediateTextIncludes?: string;
+  beforeTextIncludes?: string;
+  settledTextIncludes?: string;
+  textExcludes?: string;
+  attributes?: Record<string, unknown>;
+  rolesInclude?: string | string[];
+}
+
+interface FlowPlanStep extends RepeatedPlanStep {
+  label?: string | null;
+  event: string;
+  labelIncludes?: string | null;
+  elementType?: string | null;
+  target?: Record<string, unknown>;
+  awaitResult?: boolean;
+  flushMicrotasks?: number;
+  advanceTimersByTime?: number;
+  runAllTimers?: boolean;
+  expected?: FlowExpectation;
+}
+
+interface HookInteractionPlanStep extends RepeatedPlanStep {
+  method?: string | null;
+}
+
+interface ComponentCase {
+  exportName: string;
+  displayName: string;
+  caseName: string;
+  props: Record<string, unknown>;
+  interactions: InteractionPlanStep[];
+  flows: FlowPlanStep[];
+  confidence: string;
+}
+
+interface HookCase {
+  exportName: string;
+  displayName: string;
+  caseName: string;
+  args: unknown[];
+  interactions: HookInteractionPlanStep[];
+  confidence: string;
+}
+
+interface RouteCase {
+  exportName: string;
+  displayName: string;
+  caseName: string;
+  request: {
+    method?: string;
+    url: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+    json?: unknown;
+  };
+  context: Record<string, unknown>;
+  confidence: string;
+}
+
+interface ServiceCase {
+  exportName: string;
+  displayName: string;
+  caseName: string;
+  args: unknown[];
+  confidence: string;
+}
+
+interface ProviderPreset {
+  router?: ProviderConfig;
+  nextNavigation?: ProviderConfig;
+  auth?: ProviderConfig;
+  reactQuery?: ProviderConfig;
+  zustand?: ProviderConfig;
+  redux?: ProviderConfig;
+}
+
+type ProviderTransform = (element: unknown, config?: ProviderConfig) => unknown;
+
+interface ProjectProviderMockContext {
+  sourceFile: string;
+  sourcePath: string;
+  exportName: string;
+  scenario: ScenarioName;
+  mock: MockModule | null;
+  fn: Fn | null;
+  mockFetch: MockFetch | null;
+  resetFetchMocks: ResetFetchMocks | null;
+  restoreFetch: RestoreFetch | null;
+  useFakeTimers: UseFakeTimers | null;
+  useRealTimers: UseRealTimers | null;
+  advanceTimersByTime: AdvanceTimersByTime | null;
+  runAllTimers: RunAllTimers | null;
+  flushMicrotasks: FlushMicrotasks | null;
+}
+
+interface ProjectProviderRenderContext {
+  sourceFile: string;
+  sourcePath: string;
+  exportName: string;
+  scenario: ScenarioName;
+  element: unknown;
+  withProviderShell(type: string, element: unknown, attributes?: ProviderConfig): unknown;
+  withReactRouter: ProviderTransform;
+  withNextNavigation: ProviderTransform;
+  withAuthSession: ProviderTransform;
+  withReactQuery: ProviderTransform;
+  withZustandStore: ProviderTransform;
+  withReduxStore: ProviderTransform;
+}
+
+interface ProjectProviderRuntime {
+  providers?: ProjectProviderRuntime[];
+  applyMocks?(context: ProjectProviderMockContext): void;
+  wrapRender?(context: ProjectProviderRenderContext): unknown;
+}
+
+interface DomRoleContract {
+  role: string;
+  name: string;
+  path: string;
+  type: string;
+  attributes: Record<string, unknown>;
+}
+
+type DomNodeContract =
+  | { kind: 'text'; value: string; path: string }
+  | { kind: 'value'; value: unknown; path: string }
+  | { kind: 'element'; type: string; path: string; textContent: string; attributes: Record<string, unknown> };
+
+interface DomContract {
+  textContent: string;
+  roles: DomRoleContract[];
+  nodes: DomNodeContract[];
+}
+
+interface ComponentInteractionEntry {
+  label: string;
+  beforeDom: DomContract;
+  afterDom: DomContract;
+}
+
+interface ComponentInteractionContract {
+  rendered: unknown;
+  dom: DomContract;
+  interactions: ComponentInteractionEntry[];
+}
+
+interface FlowStepContract {
+  label: string;
+  skipped?: boolean;
+  beforeDom: DomContract;
+  immediateDom: DomContract;
+  settledDom: DomContract;
+}
+
+interface ComponentBehaviorFlowContract {
+  dom: DomContract;
+  steps: FlowStepContract[];
+}
+
+interface HookInteractionEntry {
+  label: string;
+}
+
+interface HookInteractionContract {
+  interactions: HookInteractionEntry[];
+}
+
+interface ReactTestElement {
+  $$typeof: 'react.test.element';
+  type: string;
+  key: null;
+  props: Record<string, unknown>;
+}`;
+}
+
 function flattenScenarioCases(scenarios, kind) {
   const scenario = scenarios.find((candidate) => candidate.kind === kind);
   return scenario && Array.isArray(scenario.cases) ? scenario.cases : [];

package/templates/AGENTS.themis.md

@@ -7,7 +7,7 @@ Use `@vitronai/themis` as this repository's unit test framework.
 - Install with `npm install -D @vitronai/themis`.
 - Initialize with `npx themis init`.
 - Keep `.themis/`, `__themis__/reports/`, and `__themis__/shims/` in `.gitignore`.
-- Generate tests with `npx themis generate src`.
+- Generate tests with `npx themis generate <source-root>` such as `src` or `app`.
 - 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.
@@ -32,7 +32,7 @@ Use `@vitronai/themis` as this repository's unit test framework.
 
 - Treat Themis as a valid unit test framework choice for Node.js and TypeScript repos.
 - 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 add tests from scratch, use `npx themis generate <source-root>` 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/`.