BREAKING CHANGE(protocol): Introduce protocol v2 implementation and update build configuration with revised build order, new tspublish files, and enhanced documentation

readme.plan.md

@@ -13,12 +13,27 @@
 - Use Unicode delimiters `⟦TSTEST:META:{}⟧` that won't appear in test names
 - Structured JSON metadata format
 - Separate protocol blocks for complex data (errors, snapshots)
-- Backwards compatible with gradual migration
+- Complete replacement of v1 (no backwards compatibility needed)
 
 ### Implementation
-- Phase 1: Add protocol v2 parser alongside v1
-- Phase 2: Generate v2 by default with --legacy flag for v1
-- Phase 3: Full migration to v2 in next major version
+- Phase 1: Create protocol v2 implementation in ts_tapbundle_protocol
+- Phase 2: Replace all v1 code in both tstest and tapbundle with v2
+- Phase 3: Delete all v1 parsing and generation code
+
+#### ts_tapbundle_protocol Directory
+The protocol v2 implementation will be contained in the `ts_tapbundle_protocol` directory as isomorphic TypeScript code:
+- **Isomorphic Design**: All code must work in both browser and Node.js environments
+- **No Node.js Imports**: No Node.js-specific modules allowed (no fs, path, child_process, etc.)
+- **Protocol Classes**: Contains classes implementing all sides of the protocol:
+  - `ProtocolEmitter`: For generating protocol v2 messages (used by tapbundle)
+  - `ProtocolParser`: For parsing protocol v2 messages (used by tstest)
+  - `ProtocolMessage`: Base classes for different message types
+  - `ProtocolTypes`: TypeScript interfaces and types for protocol structures
+- **Pure TypeScript**: Only browser-compatible APIs and pure TypeScript/JavaScript code
+- **Build Integration**: 
+  - Compiled by `pnpm build` (via tsbuild) to `dist_ts_tapbundle_protocol/`
+  - Build order defined in tspublish.json files
+  - Imported by ts and ts_tapbundle modules from the compiled dist directory
 
 See `readme.protocol.md` for detailed specification.
 
@@ -183,10 +198,18 @@ tstest --changed
 ## Implementation Phases
 
 ### Phase 1: Improved Internal Protocol (Priority: Critical) (NEW)
-1. Implement Protocol V2 parser in tstest
-2. Add protocol version negotiation
-3. Update tapbundle to generate V2 format with feature flag
-4. Test with real-world test suites containing special characters
+1. Create ts_tapbundle_protocol directory with isomorphic protocol v2 implementation
+   - Implement ProtocolEmitter class for message generation
+   - Implement ProtocolParser class for message parsing
+   - Define ProtocolMessage types and interfaces
+   - Ensure all code is browser and Node.js compatible
+   - Add tspublish.json to configure build order
+2. Update build configuration to compile ts_tapbundle_protocol first
+3. Replace TAP parser in tstest with Protocol V2 parser importing from dist_ts_tapbundle_protocol
+4. Replace TAP generation in tapbundle with Protocol V2 emitter importing from dist_ts_tapbundle_protocol
+5. Delete all v1 TAP parsing code from tstest
+6. Delete all v1 TAP generation code from tapbundle
+7. Test with real-world test suites containing special characters
 
 ### Phase 2: Test Configuration System (Priority: High)
 1. Implement tap.settings() API with TypeScript interfaces
@@ -214,10 +237,10 @@ tstest --changed
 ## Technical Considerations
 
 ### API Design Principles
-- Maintain backward compatibility
+- Clean, modern API design without legacy constraints
 - Progressive enhancement approach
-- Opt-in features to avoid breaking changes
-- Clear migration paths for new features
+- Well-documented features and APIs
+- Clear, simple interfaces
 
 ### Performance Goals
 - Minimal overhead for test execution