BREAKING CHANGE(core): major architectural refactoring with cross-platform support and SmartRequest rename

readme.hints.md

@@ -2,7 +2,7 @@
 
 ## Core Features
 - supports http
-- supports https
+- supports https  
 - supports unix socks
 - supports formData
 - supports file uploads
@@ -11,44 +11,69 @@
 - written in TypeScript
 - continuously updated
 - uses node native http and https modules
+- supports both Node.js and browser environments
 - used in modules like @push.rocks/smartproxy and @api.global/typedrequest
 
-## Architecture Overview (as of latest refactoring)
-- The project is now structured with a clean separation between core functionality and API layers
-- Core module (ts/core/) contains the essential HTTP request logic using Node.js http/https modules
-- **Core always returns raw streams** - no parsing or body collection happens in the core request function
-- Modern API (ts/modern/) provides a fluent, chainable interface with fetch-like Response objects
-- Legacy API is maintained through a thin adapter layer for backward compatibility
+## Architecture Overview (as of v3.0.0 major refactoring)
+- The project now has a multi-layer architecture with platform abstraction
+- Base layer (ts/core_base/) contains abstract classes and unified types
+- Node.js implementation (ts/core_node/) uses native http/https modules
+- Fetch implementation (ts/core_fetch/) uses Fetch API for browser compatibility
+- Core module (ts/core/) dynamically selects the appropriate implementation based on environment
+- Client API (ts/client/) provides a fluent, chainable interface  
+- Legacy API has been completely removed in v3.0.0
 
 ## Key Components
 
-### Core Module (ts/core/)
-- `request.ts`: Core HTTP/HTTPS request logic with unix socket support and keep-alive agents
-  - `coreRequest()` always returns a raw Node.js IncomingMessage stream
-  - No response parsing or body collection happens here
-- `response.ts`: SmartResponse class providing fetch-like API
-  - Methods like `json()`, `text()`, `arrayBuffer()` handle all parsing and body collection
-  - Response body is streamed and collected only when these methods are called
+### Core Base Module (ts/core_base/)
+- `request.ts`: Abstract CoreRequest class defining the request interface
+- `response.ts`: Abstract CoreResponse class with fetch-like API
+  - Defines `stream()` method that always returns web-style ReadableStream
   - Body can only be consumed once (throws error on second attempt)
-- `types.ts`: Core TypeScript interfaces and types
-- `plugins.ts`: Centralized dependencies
+- `types.ts`: Unified TypeScript interfaces and types
+  - Single `ICoreRequestOptions` interface for all implementations
+  - Implementations handle unsupported options by throwing errors
 
-### Modern API
-- SmartRequestClient: Fluent API with method chaining
-- Returns SmartResponse objects with fetch-like methods
+### Core Node Module (ts/core_node/)
+- `request.ts`: Node.js implementation using http/https modules
+  - Supports unix socket connections and keep-alive agents
+  - Converts Node.js specific options from unified interface
+- `response.ts`: Node.js CoreResponse implementation
+  - `stream()` method converts Node.js stream to web ReadableStream
+  - `streamNode()` method returns native Node.js stream
+  - Methods like `json()`, `text()`, `arrayBuffer()` handle parsing
+
+### Core Fetch Module (ts/core_fetch/)
+- `request.ts`: Fetch API implementation for browsers
+  - Throws errors for Node.js specific options (agent, socketPath)
+  - Native support for CORS, credentials, and other browser features
+- `response.ts`: Fetch-based CoreResponse implementation
+  - `stream()` returns native web ReadableStream from response.body
+  - `streamNode()` throws error explaining it's not available in browser
+
+### Core Module (ts/core/)
+- Dynamically loads appropriate implementation based on environment
+- Uses @push.rocks/smartenv for environment detection
+- Exports unified types from core_base
+
+### Client API (ts/client/)
+- SmartRequest: Fluent API with method chaining
+- Returns CoreResponse objects with fetch-like methods
 - Supports pagination, retries, timeouts, and various response types
 
-### Binary Request Handling
-- Binary requests are handled correctly when `responseType: 'binary'` is set
-- Response body is kept as Buffer without string conversion
-- No automatic transformations applied to binary data
+### Stream Handling
+- `stream()` method always returns web-style ReadableStream<Uint8Array>
+- In Node.js, converts native streams to web streams
+- `streamNode()` available only in Node.js environment for native streams
+- Consistent API across platforms while preserving platform-specific capabilities
 
-### Legacy Compatibility
-- All legacy functions (getJson, postJson, etc.) are maintained through adapter.ts
-- Legacy API returns IExtendedIncomingMessage for backward compatibility
-- Modern API can be accessed alongside legacy API
+### Binary Request Handling
+- Binary requests handled through ArrayBuffer API
+- Response body kept as Buffer/ArrayBuffer without string conversion
+- No automatic transformations applied to binary data
 
 ## Testing
 - Use `pnpm test` to run all tests
-- Modern API tests use the new SmartResponse methods (response.json(), response.text())
-- Legacy API tests continue to use the body property directly
+- Tests use @git.zone/tstest/tapbundle for assertions
+- Separate test files for Node.js (test.node.ts) and browser (test.browser.ts)
+- Browser tests run in headless Chromium via puppeteer