Framework updates
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
63
node_modules/@jqhtml/ssr/SPECIFICATION.md
generated
vendored
63
node_modules/@jqhtml/ssr/SPECIFICATION.md
generated
vendored
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user