@git.zone/tstest 3.1.8 → 3.3.0

package/readme.md

@@ -1,262 +1,97 @@
 # @git.zone/tstest
-🧪 **A powerful, modern test runner for TypeScript** - making your test runs beautiful and informative across multiple runtimes!
+
+🧪 **A powerful, modern test runner for TypeScript** — beautiful output, multi-runtime support, and a batteries-included test framework that makes testing actually enjoyable.
 
 ## Availability and Links
-* [npmjs.org (npm package)](https://www.npmjs.com/package/@git.zone/tstest)
-* [code.foss.global (source)](https://code.foss.global/git.zone/tstest)
+
+- [npmjs.org (npm package)](https://www.npmjs.com/package/@git.zone/tstest)
+- [code.foss.global (source)](https://code.foss.global/git.zone/tstest)
 
 ## Issue Reporting and Security
 
-For reporting bugs, issues, or security vulnerabilities, please visit https://community.foss.global/. This is the central community hub for all issue reporting. Developers who want to sign a contribution agreement and go through identification can also get a code.foss.global account to submit Pull Requests directly.
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
 
 ## Why tstest?
 
-**tstest** is a TypeScript test runner that makes testing delightful. It's designed for modern development workflows with beautiful output, flexible test execution, and powerful features that make debugging a breeze.
-
-### ✨ Key Features
-
-- 🎯 **Smart Test Execution** - Run all tests, single files, or use glob patterns
-- 🚀 **Multi-Runtime Support** - Run tests in Node.js, Deno, Bun, and Chromium
-- 🎨 **Beautiful Output** - Color-coded results with emojis and clean formatting
-- 📊 **Multiple Output Modes** - Choose from normal, quiet, verbose, or JSON output
-- 🔍 **Automatic Discovery** - Finds all your test files automatically
-- 📝 **Detailed Logging** - Optional file logging for debugging
-- ⚡ **Performance Metrics** - See which tests are slow
-- 🤖 **CI/CD Ready** - JSON output mode for automation
-- 🏷️ **Tag-based Filtering** - Run only tests with specific tags
-- 🎯 **Parallel Test Execution** - Run tests in parallel groups
-- 🔧 **Test Lifecycle Hooks** - beforeEach/afterEach support
-- 📸 **Snapshot Testing** - Compare test outputs with saved snapshots
-- ⏳ **Timeout Control** - Set custom timeouts for tests
-- 🔁 **Retry Logic** - Automatically retry failing tests
-- 🛠️ **Test Fixtures** - Create reusable test data
-- 👀 **Watch Mode** - Automatically re-run tests on file changes
-- 📊 **Real-time Progress** - Live test execution progress updates
-- 🎨 **Visual Diffs** - Beautiful side-by-side diffs for failed assertions
-- 🔄 **Event-based Reporting** - Real-time test lifecycle events
+Most TypeScript test runners feel like an afterthought — clunky configuration, ugly output, and poor TypeScript support. **tstest** was built from the ground up for TypeScript developers who want:
+
+- 🎯 **Zero config** — Point it at your test directory and go
+- 🚀 **Multi-runtime** — Run the same tests on Node.js, Deno, Bun, and Chromium
+- 🎨 **Beautiful output** — Color-coded results with emojis, progress bars, and visual diffs
+- ⚡ **Built-in everything** — Assertions, snapshots, fixtures, retries, timeouts, parallel execution
+- 🔧 **Server-side tooling** — Free ports, HTTPS certs, ephemeral databases, S3 storage — all out of the box
 
 ## Installation
 
 ```bash
-npm install --save-dev @git.zone/tstest
-# or with pnpm
-pnpm add -D @git.zone/tstest
+pnpm install --save-dev @git.zone/tstest
 ```
 
-## Multi-Runtime Architecture
-
-tstest supports running your tests across multiple JavaScript runtimes, allowing you to verify cross-platform compatibility easily.
+## Module Exports
 
-### Supported Runtimes
+tstest ships as four modules, each optimized for a different use case:
 
-- **Node.js** - Default runtime, uses tsrun for TypeScript execution
-- **Chromium** - Browser environment testing with full DOM support
-- **Deno** - Secure TypeScript/JavaScript runtime with modern features
-- **Bun** - Ultra-fast all-in-one JavaScript runtime
-
-### Test File Naming Convention
-
-Name your test files with runtime specifiers to control where they run:
+| Export Path | Environment | Purpose |
+|---|---|---|
+| `@git.zone/tstest` | CLI | Test runner — discovers and executes test files |
+| `@git.zone/tstest/tapbundle` | Browser + Node | Core test framework — `tap`, `expect`, lifecycle hooks |
+| `@git.zone/tstest/tapbundle_serverside` | Node.js only | Server-side utilities — ports, certs, databases, shell |
+| `@git.zone/tstest/tapbundle_protocol` | Isomorphic | TAP Protocol V2 — structured metadata, events, diffs |
 
-| Pattern | Runtimes | Example |
-|---------|----------|---------|
-| `*.ts` | Node.js only (default) | `test.api.ts` |
-| `*.node.ts` | Node.js only | `test.server.node.ts` |
-| `*.chromium.ts` | Chromium browser | `test.dom.chromium.ts` |
-| `*.deno.ts` | Deno runtime | `test.http.deno.ts` |
-| `*.bun.ts` | Bun runtime | `test.fast.bun.ts` |
-| `*.all.ts` | All runtimes (Node, Chromium, Deno, Bun) | `test.universal.all.ts` |
-| `*.node+chromium.ts` | Both Node.js and Chromium | `test.isomorphic.node+chromium.ts` |
-| `*.node+deno.ts` | Both Node.js and Deno | `test.cross.node+deno.ts` |
-| `*.deno+bun.ts` | Both Deno and Bun | `test.modern.deno+bun.ts` |
-| `*.chromium.nonci.ts` | Chromium, skip in CI | `test.visual.chromium.nonci.ts` |
-| `*.all.nonci.ts` | All runtimes, skip in CI | `test.comprehensive.all.nonci.ts` |
+## Quick Start
 
-**Multi-Runtime Examples:**
+### 1. Write a test
 
 ```typescript
-// test.api.all.ts - runs in all runtimes (Node, Chromium, Deno, Bun)
-import { expect, tap } from '@git.zone/tstest/tapbundle';
+// test/test.math.ts
+import { tap, expect } from '@git.zone/tstest/tapbundle';
 
-tap.test('universal HTTP test', async () => {
-  const response = await fetch('https://api.example.com/test');
-  expect(response.status).toEqual(200);
+tap.test('should add numbers', async () => {
+  expect(2 + 2).toEqual(4);
 });
 
-export default tap.start();
-```
-
-```typescript
-// test.api.node+deno+bun.ts - runs in specific runtimes
-import { expect, tap } from '@git.zone/tstest/tapbundle';
-
-tap.test('cross-runtime HTTP test', async () => {
-  const response = await fetch('https://api.example.com/test');
-  expect(response.status).toEqual(200);
+tap.test('should handle async operations', async (tools) => {
+  await tools.delayFor(100);
+  const result = await fetchData();
+  expect(result).toBeTruthy();
 });
 
 export default tap.start();
 ```
 
-### Runtime Execution Order
-
-When multiple runtimes are specified, tests execute in this order:
-1. Node.js
-2. Bun
-3. Deno
-4. Chromium
-
-### Legacy Naming (Deprecated)
-
-The following patterns are still supported but deprecated. Use the migration tool to update:
-
-| Legacy Pattern | Modern Equivalent | Migration Command |
-|----------------|-------------------|-------------------|
-| `*.browser.ts` | `*.chromium.ts` | `tstest migrate` |
-| `*.both.ts` | `*.node+chromium.ts` | `tstest migrate` |
-
-When running legacy files, tstest shows a deprecation warning with the suggested new name.
-
-### Migration Tool
-
-Migrate your test files from legacy naming to the new convention:
+### 2. Run it
 
 ```bash
-# Dry run - see what would change
-tstest migrate --dry-run
-
-# Apply migrations (uses git mv to preserve history)
-tstest migrate --write
-```
-
-**Migration Features:**
-- ✅ Uses `git mv` to preserve file history
-- ✅ Idempotent - safe to run multiple times
-- ✅ Dry-run by default for safety
-- ✅ Colored output showing all changes
-- ✅ Handles modifiers like `.nonci` correctly
-
-Example output:
-```
-============================================================
-Test File Migration Tool
-============================================================
-
-🔍 DRY RUN MODE - No files will be modified
-
-Found 3 legacy test file(s)
-
-  Would migrate:
-    test.browser.ts
-    → test.chromium.ts
-
-  Would migrate:
-    test.both.ts
-    → test.node+chromium.ts
-
-  Would migrate:
-    test.auth.browser.nonci.ts
-    → test.auth.chromium.nonci.ts
-
-============================================================
-Summary:
-  Total legacy files: 3
-  Successfully migrated: 3
-  Errors: 0
-============================================================
-
-To apply these changes, run:
-  tstest migrate --write
-```
-
-### Runtime-Specific Permissions
-
-#### Deno Runtime
-
-Tests run with these permissions by default:
-```bash
---allow-read
---allow-env
---allow-net
---allow-write
---allow-sys
---allow-import       # Enables npm packages and Node.js built-ins
---node-modules-dir   # Node.js compatibility mode
---sloppy-imports     # Allows .js imports to resolve to .ts files
-```
-
-Configure custom permissions in your test file or via environment variables.
-
-#### Bun Runtime
-
-Bun runs with its native TypeScript support and full access to Node.js APIs.
-
-## Usage
-
-### Basic Test Execution
-
-```bash
-# Run all tests in a directory
+# Run all tests
 tstest test/
 
-# Run a specific test file
-tstest test/test.mycomponent.ts
+# Run a specific file
+tstest test/test.math.ts
 
 # Use glob patterns
-tstest "test/**/*.spec.ts"
-tstest "test/unit/*.ts"
-```
+tstest "test/**/*.ts"
 
-### Execution Modes
+# Verbose mode (shows console output)
+tstest test/ --verbose
 
-**tstest** intelligently detects how you want to run your tests:
-
-1. **Directory mode** - Recursively finds all test files
-2. **File mode** - Runs a single test file
-3. **Glob mode** - Uses pattern matching for flexible test selection
+# Watch mode
+tstest test/ --watch
+```
 
-### Command Line Options
+### 3. See beautiful output
 
-| Option | Description |
-|--------|-------------|
-| `--quiet`, `-q` | Minimal output - perfect for CI environments |
-| `--verbose`, `-v` | Show all console output from tests |
-| `--no-color` | Disable colored output |
-| `--json` | Output results as JSON |
-| `--logfile` | Save detailed logs with automatic error and diff tracking |
-| `--tags <tags>` | Run only tests with specific tags (comma-separated) |
-| `--timeout <seconds>` | Timeout test files after specified seconds |
-| `--startFrom <n>` | Start running from test file number n |
-| `--stopAt <n>` | Stop running at test file number n |
-| `--watch`, `-w` | Watch for file changes and re-run tests |
-| `--watch-ignore <patterns>` | Ignore patterns in watch mode (comma-separated) |
-| `--only` | Run only tests marked with .only |
-
-### Example Outputs
-
-#### Normal Output (Default)
 ```
 🔍 Test Discovery
    Mode: directory
    Pattern: test
    Found: 4 test file(s)
 
-━━━ Part 1: Node.js ━━━
-
-▶️  test/test.node+deno.ts (1/4)
+▶️  test/test.math.ts (1/4)
    Runtime: Node.js
-   ✅ HTTP request works (12ms)
-   ✅ JSON parsing works (3ms)
+   ✅ should add numbers (2ms)
+   ✅ should handle async operations (105ms)
    Summary: 2/2 PASSED in 1.2s
 
-━━━ Part 2: Deno ━━━
-
-▶️  test/test.node+deno.ts (1/4)
-   Runtime: Deno
-   ✅ HTTP request works (15ms)
-   ✅ JSON parsing works (2ms)
-   Summary: 2/2 PASSED in 1.1s
-
 📊 Test Summary
 ┌────────────────────────────────┐
 │ Total Files:                 4 │
@@ -269,331 +104,171 @@ tstest "test/unit/*.ts"
 ALL TESTS PASSED! 🎉
 ```
 
-#### Quiet Mode
-```
-Found 4 tests
-✅ test functionality works
-✅ api calls return expected data
-✅ error handling works correctly
-✅ performance is within limits
-
-Summary: 4/4 | 542ms | PASSED
-```
-
-#### Verbose Mode
-Shows all console output from your tests, making debugging easier:
-```
-▶️  test/api.test.ts (1/1)
-   Runtime: node.js
-   Making API call to /users...
-   Response received: 200 OK
-   Processing user data...
-   ✅ api calls return expected data (145ms)
-   Summary: 1/1 PASSED
-```
-
-#### JSON Mode
-Perfect for CI/CD pipelines:
-```json
-{"event":"discovery","count":4,"pattern":"test","executionMode":"directory"}
-{"event":"fileStart","filename":"test/test.ts","runtime":"node.js","index":1,"total":4}
-{"event":"testResult","testName":"prepare test","passed":true,"duration":1}
-{"event":"summary","summary":{"totalFiles":4,"totalTests":4,"totalPassed":4,"totalFailed":0,"totalDuration":542}}
-```
-
-## Writing Tests with tapbundle
-
-tstest includes tapbundle, a powerful TAP-based test framework. Import it from the embedded tapbundle:
-
-```typescript
-import { expect, tap } from '@git.zone/tstest/tapbundle';
-
-tap.test('my awesome test', async () => {
-  const result = await myFunction();
-  expect(result).toEqual('expected value');
-});
-
-export default tap.start();
-```
-
-**Module Exports**
-
-tstest provides multiple exports for different use cases:
-
-- `@git.zone/tstest` - Main CLI and test runner functionality
-- `@git.zone/tstest/tapbundle` - Browser-compatible test framework
-- `@git.zone/tstest/tapbundle_serverside` - Server-side testing utilities for Node.js-only tests (*.node.ts files)
-  - Execute shell commands during tests
-  - Manage environment variables on-demand with secure storage
-  - Generate self-signed HTTPS certificates for testing secure connections
-  - Create ephemeral MongoDB instances for database testing
-  - Create local S3-compatible storage for object storage testing
-  - Download and manage test assets (e.g., Docker images)
-- `@git.zone/tstest/tapbundle_protocol` - Protocol V2 emitter and parser for TAP extensions
-
-### When to Use tapbundle_serverside
-
-Use `@git.zone/tstest/tapbundle_serverside` when your tests:
-
-- Run exclusively on Node.js server-side (*.node.ts test files)
-- Need to execute shell commands or interact with the file system
-- Require environment variable management with secure on-demand prompts
-- Test HTTPS servers and need self-signed certificates
-- Interact with databases (MongoDB) and need ephemeral test instances
-- Work with object storage (S3-compatible) and need local testing
-- Require test assets like Docker images or other downloadable files
-
-**Important:** tapbundle_serverside utilities are NOT available in:
-- Browser environments
-- Deno runtime
-- Bun runtime
-
-For cross-runtime tests, only import tapbundle_serverside in `.node.ts` files where you need server-side specific functionality.
-
-## tapbundle Protocol V2
-
-tstest includes an enhanced TAP protocol (Protocol V2) that extends standard TAP 13 with additional metadata while maintaining backwards compatibility.
-
-### Overview
-
-Protocol V2 adds structured metadata to TAP output using Unicode markers (`⟦TSTEST:...⟧`) that standard TAP parsers safely ignore. This allows for:
-
-- **Timing information** - Test execution duration in milliseconds
-- **Structured errors** - Stack traces, diffs, and detailed error data
-- **Test events** - Real-time progress and lifecycle events
-- **Snapshots** - Snapshot testing data exchange
-- **Custom metadata** - Tags, retry counts, file locations
-
-### Using the Protocol
-
-```typescript
-import {
-  ProtocolEmitter,
-  ProtocolParser,
-  PROTOCOL_MARKERS,
-  PROTOCOL_VERSION
-} from '@git.zone/tstest/tapbundle_protocol';
-
-// Create an emitter
-const emitter = new ProtocolEmitter();
-
-// Emit protocol header
-console.log(emitter.emitProtocolHeader());
-// Output: ⟦TSTEST:PROTOCOL:2.0.0⟧
-
-// Emit TAP version
-console.log(emitter.emitTapVersion(13));
-// Output: TAP version 13
-
-// Emit a test result with metadata
-const testResult = {
-  ok: true,
-  testNumber: 1,
-  description: 'user authentication works',
-  metadata: {
-    time: 123,
-    tags: ['auth', 'unit']
-  }
-};
-console.log(emitter.emitTest(testResult).join('\n'));
-// Output: ok 1 - user authentication works ⟦TSTEST:time:123⟧
-//         ⟦TSTEST:META:{"tags":["auth","unit"]}⟧
-```
-
-### Protocol Markers
-
-```typescript
-PROTOCOL_MARKERS = {
-  START: '⟦TSTEST:',
-  END: '⟧',
-  META_PREFIX: 'META:',
-  ERROR_PREFIX: 'ERROR',
-  SNAPSHOT_PREFIX: 'SNAPSHOT:',
-  SKIP_PREFIX: 'SKIP:',
-  TODO_PREFIX: 'TODO:',
-  EVENT_PREFIX: 'EVENT:'
-}
-```
-
-### Use Cases
-
-#### Creating Custom Test Runners
+## Multi-Runtime Architecture
 
-```typescript
-import { ProtocolEmitter } from '@git.zone/tstest/tapbundle_protocol';
+tstest supports running your tests across **four JavaScript runtimes**, letting you verify cross-platform compatibility with zero extra effort.
 
-const emitter = new ProtocolEmitter();
-
-// Emit header and version
-console.log(emitter.emitProtocolHeader());
-console.log(emitter.emitTapVersion(13));
-console.log(emitter.emitPlan({ start: 1, end: 2 }));
+### Test File Naming Convention
 
-// Run your tests and emit results
-const startTime = Date.now();
-// ... run test ...
-const duration = Date.now() - startTime;
+Name your test files with runtime specifiers to control where they run:
 
-console.log(emitter.emitTest({
-  ok: true,
-  testNumber: 1,
-  description: 'my custom test',
-  metadata: { time: duration }
-}).join('\n'));
-```
+| Pattern | Runtimes | Example |
+|---------|----------|---------|
+| `*.ts` | Node.js (default) | `test.api.ts` |
+| `*.node.ts` | Node.js only | `test.server.node.ts` |
+| `*.chromium.ts` | Chromium browser | `test.dom.chromium.ts` |
+| `*.deno.ts` | Deno | `test.http.deno.ts` |
+| `*.bun.ts` | Bun | `test.fast.bun.ts` |
+| `*.all.ts` | All runtimes | `test.universal.all.ts` |
+| `*.node+chromium.ts` | Node.js + Chromium | `test.isomorphic.node+chromium.ts` |
+| `*.node+deno.ts` | Node.js + Deno | `test.cross.node+deno.ts` |
+| `*.chromium.nonci.ts` | Chromium, skip in CI | `test.visual.chromium.nonci.ts` |
 
-#### Parsing tapbundle Output
+### Runtime Execution Order
 
-```typescript
-import { ProtocolParser } from '@git.zone/tstest/tapbundle_protocol';
+When multiple runtimes are specified, tests execute in this order: **Node.js → Bun → Deno → Chromium**
 
-const parser = new ProtocolParser();
+### Migration from Legacy Naming
 
-// Parse TAP output line by line
-parser.parseLine('⟦TSTEST:PROTOCOL:2.0.0⟧');
-parser.parseLine('TAP version 13');
-parser.parseLine('1..1');
-parser.parseLine('ok 1 - test name ⟦TSTEST:time:123⟧');
+```bash
+# Dry run — see what would change
+tstest migrate --dry-run
 
-// Get parsed results
-const results = parser.getResults();
-console.log(results);
+# Apply migrations (uses git mv to preserve history)
+tstest migrate --write
 ```
 
-### Backwards Compatibility
+| Legacy Pattern | Modern Equivalent |
+|---|---|
+| `*.browser.ts` | `*.chromium.ts` |
+| `*.both.ts` | `*.node+chromium.ts` |
 
-Protocol V2 is fully backwards compatible with standard TAP 13. The Unicode markers are treated as comments by standard TAP parsers, so Protocol V2 output can be consumed by any TAP-compliant tool:
+## CLI Options
 
-```
-⟦TSTEST:PROTOCOL:2.0.0⟧    ← Ignored by standard TAP parsers
-TAP version 13               ← Standard TAP
-1..2                         ← Standard TAP
-ok 1 - test ⟦TSTEST:time:45⟧ ← TAP parsers see: "ok 1 - test"
-ok 2 - another test          ← Standard TAP
-```
+| Option | Description |
+|---|---|
+| `--quiet`, `-q` | Minimal output — perfect for CI |
+| `--verbose`, `-v` | Show all console output from tests |
+| `--no-color` | Disable colored output |
+| `--json` | Output results as JSON (CI/CD pipelines) |
+| `--logfile` | Save detailed logs with error/diff tracking |
+| `--tags <tags>` | Run only tests with specific tags |
+| `--timeout <seconds>` | Timeout test files after N seconds |
+| `--startFrom <n>` | Start from test file number N |
+| `--stopAt <n>` | Stop at test file number N |
+| `--watch`, `-w` | Re-run tests on file changes |
+| `--watch-ignore <patterns>` | Ignore patterns in watch mode |
+| `--only` | Run only tests marked with `.only` |
 
-## tapbundle Test Framework
+## Writing Tests with tapbundle
 
-### Basic Test Syntax
+### Basic Syntax
 
 ```typescript
 import { tap, expect } from '@git.zone/tstest/tapbundle';
 
-// Basic test
-tap.test('should perform basic arithmetic', async () => {
+tap.test('basic test', async () => {
   expect(2 + 2).toEqual(4);
 });
 
-// Async test with tools
-tap.test('async operations', async (tools) => {
-  await tools.delayFor(100); // delay for 100ms
-  const result = await fetchData();
-  expect(result).toBeDefined();
+tap.test('with tools', async (tools) => {
+  await tools.delayFor(100);
+  tools.timeout(5000);
+  expect(true).toBeTrue();
 });
 
-// Start test execution
 export default tap.start();
 ```
 
-### Test Modifiers and Chaining
+### Test Modifiers
 
 ```typescript
-// Skip a test
-tap.skip.test('not ready yet', async () => {
-  // This test will be skipped
-});
+// Skip
+tap.skip.test('not ready yet', async () => { /* skipped */ });
 
-// Run only this test (exclusive)
-tap.only.test('focus on this', async () => {
-  // Only this test will run
-});
+// Only (exclusive)
+tap.only.test('focus on this', async () => { /* only this runs */ });
 
-// Todo test - creates actual test object marked as todo
-tap.todo.test('implement later', async () => {
-  // This test will be counted but marked as todo
-});
+// Todo
+tap.todo.test('implement later', async () => { /* marked as todo */ });
 
-// Chaining modifiers
+// Fluent chaining
 tap.timeout(5000)
    .retry(3)
    .tags('api', 'integration')
-   .test('complex test', async (tools) => {
-     // Test with 5s timeout, 3 retries, and tags
-   });
+   .test('complex test', async (tools) => { /* configured */ });
 ```
 
 ### Test Organization with describe()
 
 ```typescript
 tap.describe('User Management', () => {
-  let testDatabase;
-
   tap.beforeEach(async () => {
-    testDatabase = await createTestDB();
+    // setup before each test
   });
 
   tap.afterEach(async () => {
-    await testDatabase.cleanup();
+    // cleanup after each test
   });
 
-  tap.test('should create user', async () => {
-    const user = await testDatabase.createUser({ name: 'John' });
-    expect(user.id).toBeDefined();
-  });
+  tap.test('should create user', async () => { /* ... */ });
+  tap.test('should delete user', async () => { /* ... */ });
 
-  tap.describe('User Permissions', () => {
-    tap.test('should set admin role', async () => {
-      // Nested describe blocks
-    });
+  tap.describe('Permissions', () => {
+    tap.test('should set admin role', async () => { /* ... */ });
   });
 });
 ```
 
-### Test Tools (Available in Test Function)
-
-Every test function receives a `tools` parameter with utilities:
+### Pre-Tasks and Post-Tasks
 
 ```typescript
-tap.test('using test tools', async (tools) => {
-  // Delay utilities
-  await tools.delayFor(1000); // delay for 1000ms
-  await tools.delayForRandom(100, 500); // random delay between 100-500ms
+tap.preTask('setup database', async () => {
+  await initializeDatabase();
+});
 
-  // Skip test conditionally
-  tools.skipIf(process.env.CI === 'true', 'Skipping in CI');
+tap.test('uses the database', async () => { /* ... */ });
 
-  // Skip test unconditionally
-  if (!apiKeyAvailable) {
-    tools.skip('API key not available');
-  }
+tap.postTask('cleanup database', async () => {
+  await cleanupDatabase();
+});
+```
 
-  // Mark as todo
-  tools.todo('Needs implementation');
+### Test Tools
 
-  // Retry configuration
-  tools.retry(3); // Set retry count
+Every test function receives a `tools` parameter packed with utilities:
 
-  // Timeout configuration
-  tools.timeout(10000); // Set timeout to 10s
+```typescript
+tap.test('tools demo', async (tools) => {
+  // ⏱️ Delays
+  await tools.delayFor(1000);
+  await tools.delayForRandom(100, 500);
 
-  // Context sharing between tests
+  // ⏭️ Skip
+  tools.skipIf(process.env.CI === 'true', 'Skipping in CI');
+  tools.skip('reason');
+
+  // 🔁 Retry & timeout
+  tools.retry(3);
+  tools.timeout(10000);
+
+  // 📦 Context sharing between tests
   tools.context.set('userId', 12345);
   const userId = tools.context.get('userId');
 
-  // Deferred promises
+  // 🔮 Deferred promises
   const deferred = tools.defer();
   setTimeout(() => deferred.resolve('done'), 100);
   await deferred.promise;
 
-  // Colored console output
-  const coloredString = await tools.coloredString('Success!', 'green');
-  console.log(coloredString);
-
-  // Error handling helper
+  // 🎯 Error capture
   const error = await tools.returnError(async () => {
     throw new Error('Expected error');
   });
   expect(error).toBeInstanceOf(Error);
+
+  // ✅ Allow failure (test won't fail the suite)
+  tools.allowFailure();
 });
 ```
 
@@ -602,41 +277,25 @@ tap.test('using test tools', async (tools) => {
 ```typescript
 tap.test('snapshot test', async (tools) => {
   const output = generateComplexOutput();
-
-  // Compare with saved snapshot
   await tools.matchSnapshot(output);
-
-  // Named snapshots for multiple checks in one test
   await tools.matchSnapshot(output.header, 'header');
-  await tools.matchSnapshot(output.body, 'body');
 });
 
-// Update snapshots with: UPDATE_SNAPSHOTS=true tstest test/
+// Update snapshots: UPDATE_SNAPSHOTS=true tstest test/
 ```
 
 ### Test Fixtures
 
 ```typescript
-// Define reusable fixtures
 tap.defineFixture('testUser', async (data) => ({
   id: Date.now(),
   name: data?.name || 'Test User',
   email: data?.email || 'test@example.com',
-  created: new Date()
 }));
 
-tap.defineFixture('testPost', async (data) => ({
-  id: Date.now(),
-  title: data?.title || 'Test Post',
-  authorId: data?.authorId || 1
-}));
-
-// Use fixtures in tests
 tap.test('fixture test', async (tools) => {
   const user = await tools.fixture('testUser', { name: 'John' });
-  const post = await tools.fixture('testPost', { authorId: user.id });
-
-  expect(post.authorId).toEqual(user.id);
+  expect(user.name).toEqual('John');
 
   // Factory pattern for multiple instances
   const users = await tools.factory('testUser').createMany(5);
@@ -644,274 +303,229 @@ tap.test('fixture test', async (tools) => {
 });
 ```
 
-### Parallel Test Execution
+### Parallel Execution
 
 ```typescript
-// Parallel tests within a file
-tap.testParallel('parallel test 1', async () => {
-  await heavyOperation();
-});
+// Within a file
+tap.parallel().test('parallel test 1', async () => { /* ... */ });
+tap.parallel().test('parallel test 2', async () => { /* ... */ });
 
-tap.testParallel('parallel test 2', async () => {
-  await anotherHeavyOperation();
-});
-
-// File naming for parallel groups
-// test.api.para__1.ts - runs in parallel with other para__1 files
-// test.db.para__1.ts - runs in parallel with other para__1 files
-// test.auth.para__2.ts - runs after para__1 group completes
+// Across files — same suffix = parallel group
+// test.api.para__1.ts  ←─ run together
+// test.db.para__1.ts   ←─ run together
+// test.auth.para__2.ts ←─ runs after para__1 completes
 ```
 
-### Assertions with expect()
+### Assertions (expect)
 
-tapbundle uses @push.rocks/smartexpect for assertions:
+tapbundle uses [@push.rocks/smartexpect](https://code.foss.global/push.rocks/smartexpect) for assertions with automatic diff generation on failures:
 
 ```typescript
-// Basic assertions
+// Equality
 expect(value).toEqual(5);
-expect(value).not.toEqual(10);
 expect(obj).toDeepEqual({ a: 1, b: 2 });
 
-// Type assertions
+// Types
 expect('hello').toBeTypeofString();
 expect(42).toBeTypeofNumber();
-expect(true).toBeTypeofBoolean();
 expect([]).toBeArray();
-expect({}).toBeTypeOf('object');
 
-// Comparison assertions
+// Comparisons
 expect(5).toBeGreaterThan(3);
-expect(3).toBeLessThan(5);
-expect(5).toBeGreaterThanOrEqual(5);
-expect(5).toBeLessThanOrEqual(5);
 expect(0.1 + 0.2).toBeCloseTo(0.3, 10);
 
 // Truthiness
 expect(true).toBeTrue();
-expect(false).toBeFalse();
-expect('text').toBeTruthy();
-expect(0).toBeFalsy();
 expect(null).toBeNull();
 expect(undefined).toBeUndefined();
-expect(null).toBeNullOrUndefined();
 
-// String assertions
+// Strings
 expect('hello world').toStartWith('hello');
 expect('hello world').toEndWith('world');
 expect('hello world').toInclude('lo wo');
 expect('hello world').toMatch(/^hello/);
-expect('option').toBeOneOf(['choice', 'option', 'alternative']);
 
-// Array assertions
+// Arrays
 expect([1, 2, 3]).toContain(2);
 expect([1, 2, 3]).toContainAll([1, 3]);
-expect([1, 2, 3]).toExclude(4);
 expect([1, 2, 3]).toHaveLength(3);
-expect([]).toBeEmptyArray();
-expect([{ id: 1 }]).toContainEqual({ id: 1 });
 
-// Object assertions
+// Objects
 expect(obj).toHaveProperty('name');
-expect(obj).toHaveProperty('user.email', 'test@example.com');
-expect(obj).toHaveDeepProperty(['level1', 'level2']);
 expect(obj).toMatchObject({ name: 'John' });
 
-// Function assertions
-expect(() => { throw new Error('test'); }).toThrow();
-expect(() => { throw new Error('test'); }).toThrow(Error);
-expect(() => { throw new Error('test error'); }).toThrowErrorMatching(/test/);
-expect(myFunction).not.toThrow();
-
-// Promise assertions
-await expect(Promise.resolve('value')).resolves.toEqual('value');
-await expect(Promise.reject(new Error('fail'))).rejects.toThrow();
-
-// Custom assertions
-expect(7).customAssertion(
-  value => value % 2 === 1,
-  'Value is not odd'
-);
+// Functions & Promises
+expect(() => { throw new Error(); }).toThrow();
+await expect(Promise.resolve('val')).resolves.toEqual('val');
+await expect(Promise.reject(new Error())).rejects.toThrow();
+
+// Custom
+expect(7).customAssertion(v => v % 2 === 1, 'Value is not odd');
 ```
 
-### Pre-tasks
+## Server-Side Tools (tapbundle_serverside)
 
-Run setup tasks before tests start:
+For Node.js-only tests, import server-side utilities:
 
 ```typescript
-tap.preTask('setup database', async () => {
-  await initializeTestDatabase();
-  console.log('Database initialized');
-});
+import { tapNodeTools } from '@git.zone/tstest/tapbundle_serverside';
+import { tap, expect } from '@git.zone/tstest/tapbundle';
+```
+
+### 🌐 Network Utilities
+
+Find free local ports for test servers — no more port conflicts:
 
-tap.preTask('load environment', async () => {
-  await loadTestEnvironment();
+```typescript
+tap.test('should start server on free port', async () => {
+  // Single free port (random in range 3000–60000)
+  const port = await tapNodeTools.findFreePort();
+
+  // Custom range
+  const port2 = await tapNodeTools.findFreePort({ startPort: 8000, endPort: 9000 });
+
+  // With exclusions
+  const port3 = await tapNodeTools.findFreePort({ exclude: [8080, 8443] });
 });
 
-// Pre-tasks run in order before any tests
+tap.test('should allocate multiple ports', async () => {
+  // Multiple distinct ports
+  const [httpPort, wsPort, adminPort] = await tapNodeTools.findFreePorts(3);
+
+  // Consecutive port range (e.g., 4000, 4001, 4002)
+  const portRange = await tapNodeTools.findFreePortRange(3, {
+    startPort: 20000,
+    endPort: 30000,
+  });
+});
 ```
 
-### Tag-based Test Filtering
+### 🔒 HTTPS Certificates
+
+Generate self-signed certs for testing secure connections:
 
 ```typescript
-// Tag individual tests
-tap.tags('unit', 'api')
-   .test('api unit test', async () => {
-     // Test code
-   });
-
-tap.tags('integration', 'slow')
-   .test('database integration', async () => {
-     // Test code
-   });
-
-// Run only tests with specific tags
-// tstest test/ --tags unit,api
+tap.test('should serve over HTTPS', async () => {
+  const { key, cert } = await tapNodeTools.createHttpsCert('localhost');
+  const server = https.createServer({ key, cert }, handler);
+  server.listen(port);
+});
 ```
 
-### Context Sharing
-
-Share data between tests:
+### 💻 Shell Commands
 
 ```typescript
-tap.test('first test', async (tools) => {
-  const sessionId = await createSession();
-  tools.context.set('sessionId', sessionId);
-});
+const result = await tapNodeTools.runCommand('ls -la');
+console.log(result.exitCode); // 0
+```
 
-tap.test('second test', async (tools) => {
-  const sessionId = tools.context.get('sessionId');
-  expect(sessionId).toBeDefined();
+### 🔐 Environment Variables
 
-  // Cleanup
-  tools.context.delete('sessionId');
-});
+```typescript
+const apiKey = await tapNodeTools.getEnvVarOnDemand('GITHUB_API_KEY');
+// Prompts if not set, stores in .nogit/.env for future use
 ```
 
-### Browser Testing with webhelpers
+### 🗄️ Ephemeral MongoDB
 
-For browser-specific tests:
+```typescript
+const mongo = await tapNodeTools.createSmartmongo();
+// ... run database tests ...
+await mongo.stop();
+```
+
+### 📦 Local S3 Storage
 
 ```typescript
-import { tap, webhelpers } from '@git.zone/tstest/tapbundle';
+const s3 = await tapNodeTools.createSmarts3();
+// ... run object storage tests ...
+await s3.stop();
+```
 
-tap.test('DOM manipulation', async () => {
-  // Create DOM elements from HTML strings
-  const element = await webhelpers.fixture(webhelpers.html`
-    <div class="test-container">
-      <h1>Test Title</h1>
-      <button id="test-btn">Click Me</button>
-    </div>
-  `);
+## Test File Directives
 
-  expect(element.querySelector('h1').textContent).toEqual('Test Title');
+Control runtime behavior directly from your test files using special comment directives at the top of the file. Directives must appear before any `import` statements.
 
-  // Simulate interactions
-  const button = element.querySelector('#test-btn');
-  button.click();
-});
+### Deno Permissions
 
-tap.test('CSS testing', async () => {
-  const styles = webhelpers.css`
-    .test-class {
-      color: red;
-      font-size: 16px;
-    }
-  `;
+By default, Deno tests run with `--allow-read`, `--allow-env`, `--allow-net`, `--allow-write`, `--allow-sys`, and `--allow-import`. Add directives to request additional permissions:
 
-  // styles is a string that can be injected into the page
-  expect(styles).toInclude('color: red');
+```typescript
+// tstest:deno:allowAll
+import { tap, expect } from '@git.zone/tstest/tapbundle';
+
+tap.test('test with full Deno permissions', async () => {
+  // Runs with --allow-all (e.g., for FFI, subprocess spawning, etc.)
 });
+
+export default tap.start();
 ```
 
-### Advanced Error Handling
+### Available Directives
+
+| Directive | Effect |
+|---|---|
+| `// tstest:deno:allowAll` | Grants all Deno permissions (`--allow-all`) |
+| `// tstest:deno:allowRun` | Adds `--allow-run` for subprocess spawning |
+| `// tstest:deno:allowFfi` | Adds `--allow-ffi` for native library calls |
+| `// tstest:deno:allowHrtime` | Adds `--allow-hrtime` for high-res timers |
+| `// tstest:deno:flag:--unstable-ffi` | Passes any arbitrary Deno flag |
+| `// tstest:node:flag:--max-old-space-size=4096` | Passes flags to Node.js |
+| `// tstest:bun:flag:--smol` | Passes flags to Bun |
+
+### Multiple Directives
+
+Combine as many directives as needed:
 
 ```typescript
-tap.test('error handling', async (tools) => {
-  // Capture errors without failing the test
-  const error = await tools.returnError(async () => {
-    await functionThatThrows();
-  });
+// tstest:deno:allowRun
+// tstest:deno:allowFfi
+// tstest:deno:flag:--unstable-ffi
+import { tap, expect } from '@git.zone/tstest/tapbundle';
 
-  expect(error).toBeInstanceOf(Error);
-  expect(error.message).toEqual('Expected error message');
+tap.test('test with Rust FFI', async () => {
+  // Has --allow-run, --allow-ffi, and --unstable-ffi in addition to defaults
 });
+
+export default tap.start();
 ```
 
-### Test Wrap
+### Shared Directives via 00init.ts
 
-Create wrapped test environments:
+Directives in a `00init.ts` file apply to all test files in that directory. Test file directives are merged with (and extend) init file directives.
 
 ```typescript
-import { TapWrap } from '@git.zone/tstest/tapbundle';
-
-const tapWrap = new TapWrap({
-  before: async () => {
-    console.log('Before all tests');
-    await globalSetup();
-  },
-  after: async () => {
-    console.log('After all tests');
-    await globalCleanup();
-  }
-});
+// test/00init.ts
+// tstest:deno:allowRun
+```
 
-// Tests registered here will have the wrap lifecycle
-tapWrap.tap.test('wrapped test', async () => {
-  // This test runs with the wrap setup/teardown
-});
+```typescript
+// test/test.mytest.deno.ts
+// tstest:deno:allowFfi
+// Both --allow-run (from 00init.ts) and --allow-ffi are active
+import { tap, expect } from '@git.zone/tstest/tapbundle';
 ```
 
 ## Advanced Features
 
 ### Watch Mode
 
-Automatically re-run tests when files change:
-
 ```bash
-# Watch all files in the project
 tstest test/ --watch
-
-# Watch with custom ignore patterns
 tstest test/ --watch --watch-ignore "dist/**,coverage/**"
-
-# Short form
-tstest test/ -w
 ```
 
-**Features:**
 - 👀 Shows which files triggered the re-run
 - ⏱️ 300ms debouncing to batch rapid changes
-- 🔄 Clears console between runs for clean output
-- 📁 Intelligently ignores common non-source files
-
-### Real-time Test Progress
-
-tstest provides real-time updates during test execution:
-
-```
-▶️  test/api.test.ts (1/4)
-   Runtime: node.js
-   ⏳ Running: api endpoint validation...
-   ✅ api endpoint validation (145ms)
-   ⏳ Running: error handling...
-   ✅ error handling (23ms)
-   Summary: 2/2 PASSED
-```
+- 🔄 Clears console between runs
 
-### Visual Diffs for Failed Assertions
+### Visual Diffs
 
-When assertions fail, tstest shows beautiful side-by-side diffs:
+When assertions fail, you get beautiful diffs:
 
 ```
 ❌ should return correct user data
 
-   String Diff:
-   - Expected
-   + Received
-
-   - Hello World
-   + Hello Universe
-
    Object Diff:
    {
      name: "John",
@@ -921,255 +535,110 @@ When assertions fail, tstest shows beautiful side-by-side diffs:
    }
 ```
 
-### Enhanced Test Logging
-
-The `--logfile` option provides intelligent test logging with automatic organization:
+### Enhanced Logging
 
 ```bash
 tstest test/ --logfile
 ```
 
-**Log Organization:**
-- **Current Run**: `.nogit/testlogs/[testname].log`
-- **Previous Run**: `.nogit/testlogs/previous/[testname].log`
-- **Failed Tests**: `.nogit/testlogs/00err/[testname].log`
-- **Changed Output**: `.nogit/testlogs/00diff/[testname].log`
+| Folder | Contents |
+|---|---|
+| `.nogit/testlogs/` | Current run logs |
+| `.nogit/testlogs/previous/` | Previous run logs |
+| `.nogit/testlogs/00err/` | Failed test logs |
+| `.nogit/testlogs/00diff/` | Changed output diffs |
 
-**Features:**
-- Previous logs are automatically moved to the `previous/` folder
-- Failed tests create copies in `00err/` for quick identification
-- Tests with changed output create diff reports in `00diff/`
-- The `00err/` and `00diff/` folders are cleared on each run
+### JSON Output (CI/CD)
 
-**Example Diff Report:**
+```bash
+tstest test/ --json > test-results.json
 ```
-DIFF REPORT: test__api__integration.log
-Generated: 2025-05-24T01:29:13.847Z
-================================================================================
 
-- [Line 8]    ✅ api test passes (150ms)
-+ [Line 8]    ✅ api test passes (165ms)
-
-================================================================================
-Previous version had 40 lines
-Current version has 40 lines
+```json
+{"event":"discovery","count":4,"pattern":"test","executionMode":"directory"}
+{"event":"testResult","testName":"prepare test","passed":true,"duration":1}
+{"event":"summary","summary":{"totalFiles":4,"totalTests":4,"totalPassed":4,"totalFailed":0}}
 ```
 
-### Test Timeout Protection
+### Tag Filtering
 
-Prevent runaway tests with the `--timeout` option:
-
-```bash
-# Timeout any test file that runs longer than 60 seconds
-tstest test/ --timeout 60
-
-# Shorter timeout for unit tests
-tstest test/unit/ --timeout 10
+```typescript
+tap.tags('unit', 'api').test('api unit test', async () => { /* ... */ });
 ```
 
-When a test exceeds the timeout:
-- The test process is terminated (SIGTERM)
-- The test is marked as failed
-- An error log is created in `.nogit/testlogs/00err/`
-- Clear error message shows the timeout duration
-
-### Test File Range Control
-
-Run specific ranges of test files using `--startFrom` and `--stopAt`:
-
 ```bash
-# Run tests starting from the 5th file
-tstest test/ --startFrom 5
-
-# Run only files 5 through 10
-tstest test/ --startFrom 5 --stopAt 10
-
-# Run only the first 3 test files
-tstest test/ --stopAt 3
-```
-
-This is particularly useful for:
-- Debugging specific test failures in large test suites
-- Running tests in chunks on different CI runners
-- Quickly testing changes to specific test files
-
-The output shows which files are skipped:
-```
-⏭️  test/auth.test.ts (1/10)
-   Skipped: before start range (5)
-⏭️  test/user.test.ts (2/10)
-   Skipped: before start range (5)
-▶️  test/api.test.ts (5/10)
-   Runtime: node.js
-   ✅ api endpoints work (145ms)
+tstest test/ --tags unit,api
 ```
 
-### Performance Analysis
+### Test File Range
 
-In verbose mode, see performance metrics:
-```
-⏱️  Performance Metrics:
-   Average per test: 135ms
-   Slowest test: api integration test (486ms)
+```bash
+tstest test/ --startFrom 5 --stopAt 10  # Run files 5-10 only
 ```
 
-### Parallel Test Groups
+### Browser Testing with webhelpers
 
-Tests can be organized into parallel groups for concurrent execution:
+```typescript
+import { tap, webhelpers } from '@git.zone/tstest/tapbundle';
 
+tap.test('DOM test', async () => {
+  const element = await webhelpers.fixture(webhelpers.html`
+    <div class="container">
+      <h1>Hello</h1>
+    </div>
+  `);
+  expect(element.querySelector('h1').textContent).toEqual('Hello');
+});
 ```
-━━━ Parallel Group: para__1 ━━━
-▶️  test/auth.para__1.ts
-▶️  test/user.para__1.ts
-   ... tests run concurrently ...
-──────────────────────────────────
-
-━━━ Parallel Group: para__2 ━━━
-▶️  test/db.para__2.ts
-▶️  test/api.para__2.ts
-   ... tests run concurrently ...
-──────────────────────────────────
-```
-
-Files with the same parallel group suffix (e.g., `para__1`) run simultaneously, while different groups run sequentially.
 
-### CI/CD Integration
+### TapWrap (Global Lifecycle)
 
-For continuous integration, combine quiet and JSON modes:
-```bash
-# GitHub Actions example
-tstest test/ --json > test-results.json
-
-# Or minimal output
-tstest test/ --quiet
-```
+```typescript
+import { TapWrap } from '@git.zone/tstest/tapbundle';
 
-**Advanced CI Example:**
-```bash
-# Run tests with comprehensive logging and safety features
-tstest test/ \
-  --timeout 300 \
-  --logfile \
-  --json > test-results.json
-
-# Run specific test chunks in parallel CI jobs
-tstest test/ --startFrom 1 --stopAt 10   # Job 1
-tstest test/ --startFrom 11 --stopAt 20  # Job 2
-tstest test/ --startFrom 21              # Job 3
+const tapWrap = new TapWrap({
+  before: async () => { await globalSetup(); },
+  after: async () => { await globalCleanup(); },
+});
 ```
 
-### Debugging Failed Tests
+## tapbundle Protocol V2
 
-When tests fail, use the enhanced logging features:
+tstest includes an enhanced TAP protocol that extends TAP 13 with structured metadata while staying backwards compatible. Protocol markers (`⟦TSTEST:...⟧`) are invisible to standard TAP parsers.
 
-```bash
-# Run with logging to capture detailed output
-tstest test/ --logfile --verbose
-
-# Check error logs
-ls .nogit/testlogs/00err/
+```typescript
+import { ProtocolEmitter, ProtocolParser } from '@git.zone/tstest/tapbundle_protocol';
 
-# Review diffs for flaky tests
-cat .nogit/testlogs/00diff/test__api__endpoints.log
+// Emit
+const emitter = new ProtocolEmitter();
+console.log(emitter.emitProtocolHeader());  // ⟦TSTEST:PROTOCOL:2.0.0⟧
+console.log(emitter.emitTest({
+  ok: true, testNumber: 1, description: 'test',
+  metadata: { time: 42, tags: ['unit'] }
+}).join('\n'));
 
-# Re-run specific failed tests
-tstest test/api/endpoints.test.ts --verbose --timeout 60
+// Parse
+const parser = new ProtocolParser();
+const messages = parser.parseLine('ok 1 - test ⟦TSTEST:time:42⟧');
 ```
 
-## Changelog
-
-### Version 3.1.1
-- 🐛 Fixed TapTools parameter passing to suite lifecycle hooks (beforeAll/afterAll)
-- 📦 Updated @push.rocks/smarts3 dependency to ^3.0.0
-
-### Version 3.1.0
-- 🎯 **postTask() API** - Global teardown method for cleanup after all tests
-- 🏗️ **Suite beforeAll/afterAll** - Lifecycle hooks that run once per describe block
-- ⚡ **parallel() Fluent API** - New fluent entry point for parallel tests
-- 📚 Enhanced tapbundle documentation with complete API reference
-
-### Version 3.0.0
-- 🔥 **BREAKING:** Renamed tapbundle_node to tapbundle_serverside for clarity
-- 🔧 Migrated all server-side utilities to tapbundle_serverside
-- 📦 Improved module separation and organization
-
-### Version 2.4.0
-- 🚀 **Multi-Runtime Architecture** - Support for Deno, Bun, Node.js, and Chromium
-- 🔀 **New Naming Convention** - Flexible `.runtime1+runtime2.ts` pattern
-- 🌐 **Universal Testing** - `.all.ts` pattern runs tests on all supported runtimes
-- 🔄 **Migration Tool** - Easy migration from legacy naming (`.browser.ts`, `.both.ts`)
-- 🦕 **Deno Support** - Full Deno runtime with Node.js compatibility
-- 🐰 **Bun Support** - Ultra-fast Bun runtime integration
-- ⚡ **Dynamic Port Selection** - Random port allocation (30000-40000) prevents conflicts
-- 🏗️ **Runtime Adapter Pattern** - Extensible architecture for adding new runtimes
-- 📝 **Deprecation Warnings** - Helpful migration suggestions for legacy naming
-- ✅ **Comprehensive Tests** - Full test coverage for parser and migration tool
-
-### Version 1.11.0
-- 👀 Added Watch Mode with `--watch`/`-w` flag for automatic test re-runs
-- 📊 Implemented real-time test progress updates with event streaming
-- 🎨 Added visual diffs for failed assertions with side-by-side comparison
-- 🔄 Enhanced event-based test lifecycle reporting
-- ⚙️ Added test configuration system with `.tstest.json` files
-- 🚀 Implemented Protocol V2 with Unicode delimiters for better TAP parsing
-- 🐛 Fixed `tap.todo()` to create proper test objects
-- 🐛 Fixed `tap.skip.test()` to correctly create and count test objects
-- 🐛 Fixed `tap.only.test()` implementation with `--only` flag support
-- 📁 Added settings inheritance for cascading test configuration
-- ⏱️ Added debouncing for file change events in watch mode
-
-### Version 1.10.0
-- ⏱️ Added `--timeout <seconds>` option for test file timeout protection
-- 🎯 Added `--startFrom <n>` and `--stopAt <n>` options for test file range control
-- 📁 Enhanced `--logfile` with intelligent log organization:
-  - Previous logs moved to `previous/` folder
-  - Failed tests copied to `00err/` folder
-  - Changed tests create diff reports in `00diff/` folder
-- 🔍 Improved test discovery to show skipped files with clear reasons
-- 🐛 Fixed TypeScript compilation warnings and unused variables
-- 📊 Test summaries now include skipped file counts
-
-### Version 1.9.2
-- 🐛 Fixed test timing display issue (removed duplicate timing in output)
-- 📝 Improved internal protocol design documentation
-- 🔧 Added protocol v2 utilities for future improvements
-
-### Version 1.9.1
-- 🐛 Fixed log file naming to preserve directory structure
-- 📁 Log files now prevent collisions: `test__dir__file.log`
-
-### Version 1.9.0
-- 📚 Comprehensive documentation update
-- 🏗️ Embedded tapbundle for better integration
-- 🌐 Full browser compatibility
-
-### Version 1.8.0
-- 📦 Embedded tapbundle directly into tstest project
-- 🌐 Made tapbundle fully browser-compatible
-- 📸 Added snapshot testing with base64-encoded communication protocol
-- 🏷️ Introduced tag-based test filtering
-- 🔧 Enhanced test lifecycle hooks (beforeEach/afterEach)
-- 🎯 Fixed parallel test execution and grouping
-- ⏳ Improved timeout and retry mechanisms
-- 🛠️ Added test fixtures for reusable test data
-- 📊 Enhanced TAP parser for better test reporting
-- 🐛 Fixed glob pattern handling in shell scripts
-
 ## License and Legal Information
 
-This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
 
 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 
 ### Trademarks
 
-This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
 
 ### Company Information
 
 Task Venture Capital GmbH
-Registered at District court Bremen HRB 35230 HB, Germany
+Registered at District Court Bremen HRB 35230 HB, Germany
 
-For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
 
 By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.