BREAKING CHANGE(smartwatch): Introduce Smartwatch: cross-runtime native file watching for Node.js, Deno and Bun; rename smartchok to smartwatch and bump major version to 2.0.0

readme.hints.md

@@ -1,33 +1,82 @@
 # smartchok - Technical Hints
 
-## Chokidar 5.x Migration (2024)
+## Native File Watching (v2.0.0+)
 
-The module has been migrated to `chokidar` 5.x (from 4.x). Key changes:
+The module now uses native file watching APIs instead of chokidar, providing cross-runtime support for Node.js, Deno, and Bun.
+
+### Architecture
+
+```
+ts/
+├── smartwatch.classes.smartwatch.ts   # Main Smartwatch class
+├── smartwatch.plugins.ts              # Dependencies (smartenv, picomatch, etc.)
+├── watchers/
+│   ├── index.ts                       # Factory with runtime detection
+│   ├── interfaces.ts                  # IWatcher interface and types
+│   ├── watcher.node.ts                # Node.js/Bun implementation (fs.watch)
+│   └── watcher.deno.ts                # Deno implementation (Deno.watchFs)
+└── utils/
+    └── write-stabilizer.ts            # awaitWriteFinish polling implementation
+```
+
+### Runtime Detection
+
+Uses `@push.rocks/smartenv` v6.x for runtime detection:
+- **Node.js/Bun**: Uses native `fs.watch()` with `{ recursive: true }`
+- **Deno**: Uses `Deno.watchFs()` async iterable
 
 ### Dependencies
-- **Current**: `chokidar` 5.x and `picomatch`
-- **Historical**: Was previously using `@tempfix/watcher` before chokidar 4.x
+
+- **picomatch**: Glob pattern matching (zero deps, well-maintained)
+- **@push.rocks/smartenv**: Runtime detection (Node.js, Deno, Bun)
+- **@push.rocks/smartrx**: RxJS Subject/Observable management
+- **@push.rocks/smartpromise**: Deferred promise utilities
+- **@push.rocks/lik**: Stringmap for pattern storage
 
 ### Why picomatch?
-Chokidar 4.x+ removed built-in glob pattern support. We use `picomatch` to maintain backward compatibility and provide glob pattern matching functionality.
 
-### Implementation Details
-1. **Glob pattern extraction**: The `getGlobBase()` method extracts base directories from glob patterns
-2. **Pattern matching**: Each glob pattern is compiled to a picomatch matcher function
-3. **Event filtering**: File system events are filtered based on glob patterns before being emitted
-4. **Path normalization**: Paths are normalized to handle different formats (with/without leading ./)
+Native file watching APIs don't support glob patterns. Picomatch provides glob pattern matching with:
+- Zero dependencies
+- 164M+ weekly downloads
+- Excellent security profile
+- Full glob syntax support
 
 ### Event Handling
-Chokidar 5.x events are mapped 1:1 with smartchok events:
-- `add`, `change`, `unlink`: File events
-- `addDir`, `unlinkDir`: Directory events
-- `error`: Error events
-- `raw`: Raw events from underlying watchers
-- `ready`: Emitted when initial scan is complete
+
+Native events are normalized to a consistent interface:
+
+| Node.js/Bun Event | Deno Event | Normalized Event |
+|-------------------|------------|------------------|
+| `rename` (file exists) | `create` | `add` |
+| `rename` (file gone) | `remove` | `unlink` |
+| `change` | `modify` | `change` |
+
+### awaitWriteFinish Implementation
+
+The `WriteStabilizer` class replaces chokidar's built-in write stabilization:
+- Polls file size until stable (configurable threshold: 300ms default)
+- Configurable poll interval (100ms default)
+- Handles file deletion during write detection
+
+### Platform Requirements
+
+- **Node.js 20+**: Required for native recursive watching on all platforms
+- **Deno**: Works on all versions with `Deno.watchFs()`
+- **Bun**: Uses Node.js compatibility layer
 
 ### Testing
-All existing tests pass without modification, confirming backward compatibility is maintained.
 
-## Dev Dependencies (2024)
-- Using `@git.zone/tstest` v3.x with tapbundle (`import { tap, expect } from '@git.zone/tstest/tapbundle'`)
-- Removed deprecated `@push.rocks/tapbundle`
+```bash
+pnpm test
+```
+
+Tests verify:
+- Creating Smartwatch instance
+- Adding glob patterns
+- Receiving 'add' events for new files
+- Graceful shutdown
+
+## Dev Dependencies
+
+- Using `@git.zone/tstest` v3.x with tapbundle
+- Import from `@git.zone/tstest/tapbundle`