Framework updates

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
root
2026-03-12 19:09:07 +00:00
parent 3294fc7337
commit daa9bb2fb1
47 changed files with 2495 additions and 525 deletions

View File

@@ -544,6 +544,69 @@ jqhtml-ssr --render \
---
## Preload Data Capture and Injection Protocol
The preload system captures component data during SSR and replays it on the client to skip redundant `on_load()` calls during hydration.
### Entry Format
Each captured entry has the following structure:
```json
{
"component": "DashboardIndex",
"args": { "user_id": 123 },
"data": { "items": [...], "total": 42 }
}
```
| Field | Type | Description |
|-------|------|-------------|
| `component` | string | Component name |
| `args` | object | Component arguments (as passed at creation) |
| `data` | object | The component's `this.data` after `on_load()` completed |
### Key Generation
Preload entries are matched by a composite key of `component` + `args`. The key generation algorithm:
1. Component name is used as-is (string)
2. Args are serialized deterministically (stable JSON stringification)
3. Combined key: `component + ":" + serialized_args`
This means two components with the same name and identical args share a preload entry, which is consistent with Load Coordinator deduplication behavior.
### One-Shot Semantics
Both capture and preload use one-shot consumption:
- **`get_captured_data()`** — Returns all captured entries and clears the capture buffer. Calling again returns an empty array until new components are captured.
- **Preload entries** — Each entry is consumed on first use. When `_load()` finds a preload cache hit, it removes that entry. A second component with the same key will not find a preload hit and will call `on_load()` normally.
### Integration Points in `_load()`
The preload system integrates into the component `_load()` method with the following priority:
1. **Preload cache check** (highest priority) — If `set_preload_data()` was called and an entry matches this component's name + args, apply the data via `_apply_load_result()` and skip `on_load()` entirely.
2. **Load Coordinator check** — If another instance of the same component + args is already loading, wait for its result.
3. **Normal `on_load()`** — Call the component's `on_load()` method.
### Capture Integration in `_apply_load_result()`
When data capture is enabled (`start_data_capture()` was called), `_apply_load_result()` records the component's data if the component has an `on_load()` method. Static components (those without `on_load()`) are excluded from capture.
### API Summary
| Method | Side | Description |
|--------|------|-------------|
| `start_data_capture()` | Server | Enable capture mode (idempotent) |
| `get_captured_data()` | Server | Return and clear captured entries |
| `stop_data_capture()` | Server | Stop capture, clear all state |
| `set_preload_data(entries)` | Client | Seed preload cache; null/empty is no-op |
| `clear_preload_data()` | Client | Clear unconsumed preload entries |
---
## Future Considerations
### Streaming SSR