typedserver/readme.hints.md

# Project Hints - @api.global/typedserver

## Recent Changes (December 2025)

### Dependency Updates
- `@push.rocks/smartwatch` upgraded to v6.0.0 (cross-runtime, native fs.watch)
- `@design.estate/dees-catalog` upgraded to v3.1.1 (new icons, components)
- `@push.rocks/smartchok` replaced with `@push.rocks/smartwatch` (renamed package)
- `@push.rocks/smartfile` upgraded from v11 to v13 (major API change - `fs` module removed)
- `@push.rocks/smartfs` added for filesystem operations (v1.2.0+)
- `@push.rocks/smartenv` upgraded to v6.0.0
- `@push.rocks/smartrequest` upgraded to v5.0.1
- `@push.rocks/webrequest` upgraded to v4.0.1 (`WebRequest` renamed to `WebrequestClient`)
- Express upgraded to v5.2.1
- All `@git.zone/*` dev dependencies updated to latest

### Code Migration Notes

#### smartwatch v6.0.0
- Cross-runtime support: Node.js 20+, Deno, Bun
- Uses native `fs.watch({ recursive: true })` for performance
- Minimal dependencies (no chokidar, no FSEvents bindings)
- API unchanged: `new Smartwatch([patterns])`, `.start()`, `.stop()`, `.getObservableFor(event)`
- Events: `add`, `addDir`, `change`, `unlink`, `unlinkDir`, `error`, `ready`
- Dynamic watching: `.add(patterns)`, `.remove(pattern)`
- Status property: `'idle' | 'starting' | 'watching'`

#### dees-catalog v3.0.0+ Migration
- **DeesIcon**: New unified `icon` property with library prefixes:
  - FontAwesome: `icon="fa:check"` (prefix `fa:`)
  - Lucide: `icon="lucide:menu"` (prefix `lucide:`)
  - Legacy `iconFA` property deprecated but still supported
- **DeesToast**: New convenience methods and positioning:
  - `DeesToast.info()`, `.success()`, `.warning()`, `.error()`
  - Position options: `top-right`, `top-left`, `bottom-right`, `bottom-left`, `top-center`, `bottom-center`
- New components: DeesInputTags, DeesInputDatepicker, DeesStatsGrid, DeesPagination, DeesAppuiBase
- DeesAppuiAppbar: Hierarchical menus with keyboard navigation

#### smartfile v13 Migration
- Old: `plugins.smartfile.fs.toStringSync(path)` / `plugins.smartfile.fs.toBufferSync(path)`
- New: Use `plugins.fsInstance` (SmartFs instance with Node provider)
  - String: `await plugins.fsInstance.file(path).encoding('utf8').read() as string`
  - Buffer: `await plugins.fsInstance.file(path).read() as Buffer`

#### smartfs treeHash
- Old: `plugins.smartfile.fs.fileTreeToHash(dir, pattern)`
- New: `await plugins.fsInstance.directory(dir).recursive().treeHash()`

#### webrequest v4
- Class renamed: `WebRequest` → `WebrequestClient`

### Architecture
- `plugins.fsInstance` is a pre-configured SmartFs instance with SmartFsProviderNode
- All file operations should be async using smartfs
- Sync file operations have been removed

### Express 5 Notes
- Wildcard routes use `/{*splat}` notation
- `req.params.splat` can be an array, use `Array.isArray()` check