@symbiotejs/symbiote 3.8.3 → 3.10.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +52 -2
- package/core/AppRouter.js +97 -58
- package/core/PubSub.js +42 -11
- package/core/Symbiote.js +90 -59
- package/core/itemizeProcessor-keyed.js +88 -188
- package/core/itemizeProcessor.js +1 -12
- package/core/itemizeSetup.js +26 -3
- package/core/ownElements.js +1 -4
- package/core/resolveTemplate.js +12 -0
- package/core/tpl-processors.js +3 -3
- package/docs/README.md +5 -4
- package/docs/html-app-vs-htmx.md +55 -0
- package/docs/lifecycle.md +2 -0
- package/docs/list-rendering.md +10 -2
- package/docs/properties.md +28 -1
- package/docs/pubsub.md +3 -0
- package/docs/routing.md +15 -4
- package/docs/security.md +41 -12
- package/docs/templates.md +29 -0
- package/html-app/BaseClass.js +203 -0
- package/html-app/README.md +369 -0
- package/html-app/action-data.js +168 -0
- package/html-app/actions.js +366 -0
- package/html-app/collection-actions.js +104 -0
- package/html-app/collection-data.js +234 -0
- package/html-app/collection-items.js +45 -0
- package/html-app/conditions.js +42 -0
- package/html-app/context-data.js +185 -0
- package/html-app/context-requests.js +374 -0
- package/html-app/context-storage.js +376 -0
- package/html-app/declarations.js +55 -0
- package/html-app/examples/assets/actions.html +56 -0
- package/html-app/examples/assets/collections.html +72 -0
- package/html-app/examples/assets/components.html +25 -0
- package/html-app/examples/assets/conditional.html +29 -0
- package/html-app/examples/assets/data.html +31 -0
- package/html-app/examples/assets/guide.html +4 -0
- package/html-app/examples/assets/imports.html +11 -0
- package/html-app/examples/assets/not-found.html +4 -0
- package/html-app/examples/assets/routes.json +58 -0
- package/html-app/examples/assets/routing.html +27 -0
- package/html-app/examples/assets/state.html +32 -0
- package/html-app/examples/assets/storage.html +28 -0
- package/html-app/examples/assets/tasks.json +25 -0
- package/html-app/examples/full-app.html +147 -0
- package/html-app/examples/todo-ref.html +37 -0
- package/html-app/fetch-source.js +147 -0
- package/html-app/fragment-content.js +29 -0
- package/html-app/fragment-source.js +169 -0
- package/html-app/index.js +34 -0
- package/html-app/initial-data.js +88 -0
- package/html-app/pub-map.js +93 -0
- package/html-app/router-data.js +50 -0
- package/html-app/router-navigation.js +70 -0
- package/html-app/storage-revisions.js +130 -0
- package/html-app/sym-collection.js +142 -0
- package/html-app/sym-component.js +20 -0
- package/html-app/sym-conditional.js +141 -0
- package/html-app/sym-context.js +176 -0
- package/html-app/sym-import.js +218 -0
- package/html-app/sym-router.js +107 -0
- package/package.json +18 -8
- package/scripts/check-html-app-package.js +117 -0
- package/scripts/check-html-app-size.js +91 -0
- package/scripts/update-exports.js +4 -0
- package/skills/symbiote/SKILL.md +197 -0
- package/skills/symbiote/agents/openai.yaml +3 -0
- package/types/core/AppRouter.d.ts +13 -4
- package/types/core/AppRouter.d.ts.map +1 -1
- package/types/core/PubSub.d.ts +1 -1
- package/types/core/PubSub.d.ts.map +1 -1
- package/types/core/Symbiote.d.ts +6 -2
- package/types/core/Symbiote.d.ts.map +1 -1
- package/types/core/itemizeProcessor-keyed.d.ts.map +1 -1
- package/types/core/itemizeProcessor.d.ts.map +1 -1
- package/types/core/itemizeSetup.d.ts +1 -0
- package/types/core/itemizeSetup.d.ts.map +1 -1
- package/types/core/ownElements.d.ts +1 -1
- package/types/core/ownElements.d.ts.map +1 -1
- package/types/core/resolveTemplate.d.ts +2 -0
- package/types/core/resolveTemplate.d.ts.map +1 -0
- package/types/html-app/BaseClass.d.ts +24 -0
- package/types/html-app/BaseClass.d.ts.map +1 -0
- package/types/html-app/action-data.d.ts +15 -0
- package/types/html-app/action-data.d.ts.map +1 -0
- package/types/html-app/actions.d.ts +104 -0
- package/types/html-app/actions.d.ts.map +1 -0
- package/types/html-app/collection-actions.d.ts +12 -0
- package/types/html-app/collection-actions.d.ts.map +1 -0
- package/types/html-app/collection-data.d.ts +13 -0
- package/types/html-app/collection-data.d.ts.map +1 -0
- package/types/html-app/collection-items.d.ts +7 -0
- package/types/html-app/collection-items.d.ts.map +1 -0
- package/types/html-app/conditions.d.ts +5 -0
- package/types/html-app/conditions.d.ts.map +1 -0
- package/types/html-app/context-data.d.ts +31 -0
- package/types/html-app/context-data.d.ts.map +1 -0
- package/types/html-app/context-requests.d.ts +97 -0
- package/types/html-app/context-requests.d.ts.map +1 -0
- package/types/html-app/context-storage.d.ts +102 -0
- package/types/html-app/context-storage.d.ts.map +1 -0
- package/types/html-app/declarations.d.ts +3 -0
- package/types/html-app/declarations.d.ts.map +1 -0
- package/types/html-app/fetch-source.d.ts +23 -0
- package/types/html-app/fetch-source.d.ts.map +1 -0
- package/types/html-app/fragment-content.d.ts +6 -0
- package/types/html-app/fragment-content.d.ts.map +1 -0
- package/types/html-app/fragment-source.d.ts +14 -0
- package/types/html-app/fragment-source.d.ts.map +1 -0
- package/types/html-app/index.d.ts +9 -0
- package/types/html-app/index.d.ts.map +1 -0
- package/types/html-app/initial-data.d.ts +8 -0
- package/types/html-app/initial-data.d.ts.map +1 -0
- package/types/html-app/pub-map.d.ts +19 -0
- package/types/html-app/pub-map.d.ts.map +1 -0
- package/types/html-app/router-data.d.ts +4 -0
- package/types/html-app/router-data.d.ts.map +1 -0
- package/types/html-app/router-navigation.d.ts +3 -0
- package/types/html-app/router-navigation.d.ts.map +1 -0
- package/types/html-app/storage-revisions.d.ts +11 -0
- package/types/html-app/storage-revisions.d.ts.map +1 -0
- package/types/html-app/sym-collection.d.ts +16 -0
- package/types/html-app/sym-collection.d.ts.map +1 -0
- package/types/html-app/sym-component.d.ts +5 -0
- package/types/html-app/sym-component.d.ts.map +1 -0
- package/types/html-app/sym-conditional.d.ts +10 -0
- package/types/html-app/sym-conditional.d.ts.map +1 -0
- package/types/html-app/sym-context.d.ts +16 -0
- package/types/html-app/sym-context.d.ts.map +1 -0
- package/types/html-app/sym-import.d.ts +19 -0
- package/types/html-app/sym-import.d.ts.map +1 -0
- package/types/html-app/sym-router.d.ts +12 -0
- package/types/html-app/sym-router.d.ts.map +1 -0
- package/docs/llms-index.md +0 -49
- package/llms-full.txt +0 -5432
- package/llms.txt +0 -49
- package/scripts/build-llms.js +0 -56
package/docs/README.md
CHANGED
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
## Core Concepts
|
|
12
12
|
|
|
13
13
|
- [**Templates**](./templates.md) — HTML string templates, binding syntax, slots, element references
|
|
14
|
-
- [**Properties**](./properties.md) — State initialization, `$` proxy, subscriptions, computed properties
|
|
14
|
+
- [**Properties**](./properties.md) — State initialization, `$` proxy and merging, subscriptions, computed properties
|
|
15
15
|
- [**Context**](./context.md) — Local, named, pop-up, and shared data contexts
|
|
16
16
|
- [**List Rendering**](./list-rendering.md) — Itemize API for dynamic lists
|
|
17
17
|
- [**Lifecycle**](./lifecycle.md) — Component lifecycle callbacks and destruction
|
|
@@ -29,6 +29,8 @@
|
|
|
29
29
|
|
|
30
30
|
## Features
|
|
31
31
|
|
|
32
|
+
- [**HTML-app foundation**](../html-app/README.md) - Build applications with HTML, JSON and declarative actions
|
|
33
|
+
- [**HTML-app and htmx**](./html-app-vs-htmx.md) - Compare reactive HTML applications with HTTP-driven HTML updates
|
|
32
34
|
- [**WebMCP**](./webmcp.md) — Expose live UI state and handlers as browser-native tools
|
|
33
35
|
- [**Routing**](./routing.md) — SPA routing with path patterns, guards, lazy loading
|
|
34
36
|
- [**SSR**](./ssr.md) — Server-side rendering, streaming, hydration
|
|
@@ -39,15 +41,14 @@
|
|
|
39
41
|
|
|
40
42
|
- [**Dev Mode**](./dev-mode.md) — Verbose warnings for debugging
|
|
41
43
|
- [**TypeScript**](./typescript.md) — JSDoc types, TypeScript usage, and hybrid template checks
|
|
42
|
-
- [**Security**](./security.md) —
|
|
44
|
+
- [**Security**](./security.md) — Template trust, CSP, and agent-facing boundaries
|
|
43
45
|
|
|
44
46
|
## Additional Resources
|
|
45
47
|
|
|
46
48
|
- [Live Examples](https://rnd-pro.com/symbiote/3x/examples/) - Interactive Code Playground
|
|
47
49
|
- [Common Mistakes](./common-mistakes.md) — Patterns that frequently cause bugs
|
|
48
50
|
- [Examples](./examples.md) — 26 complete working examples
|
|
49
|
-
- [
|
|
50
|
-
- [llms-full.txt](https://rnd-pro.com/symbiote/llms-full.txt) — complete merged reference for AI context
|
|
51
|
+
- [Agent skill](../skills/symbiote/SKILL.md) — Implementation guidance for coding agents; [installation](../README.md#use-with-coding-agents)
|
|
51
52
|
- [npm](https://www.npmjs.com/package/@symbiotejs/symbiote)
|
|
52
53
|
- [GitHub Discussions](https://github.com/symbiotejs/symbiote.js/discussions)
|
|
53
54
|
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# HTML-app and htmx
|
|
2
|
+
|
|
3
|
+
Both let you describe interactions in HTML and use an external library script without an application build step. Their main difference is how an interaction produces the next view.
|
|
4
|
+
|
|
5
|
+
[htmx](https://htmx.org/docs/#introduction) makes HTTP interactions declarative. An element issues a request; the server typically returns HTML that htmx inserts into a target. [HTML-app](../html-app/README.md) makes reactive application state and record operations declarative. A control publishes a value or invokes an action, and Symbiote updates the views bound to that data.
|
|
6
|
+
|
|
7
|
+
## Adding a task
|
|
8
|
+
|
|
9
|
+
With htmx, a form can submit to an endpoint and append the returned task markup:
|
|
10
|
+
|
|
11
|
+
```html
|
|
12
|
+
<form hx-post="/tasks" hx-target="#tasks" hx-swap="beforeend">
|
|
13
|
+
<input name="title" required>
|
|
14
|
+
<button>Add task</button>
|
|
15
|
+
</form>
|
|
16
|
+
<ul id="tasks"></ul>
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
The application supplies `/tasks`, including validation, any persistence and the task's HTML. [`hx-post`](https://htmx.org/attributes/hx-post/) sends the request; [`hx-swap="beforeend"`](https://htmx.org/attributes/hx-swap/) appends the response inside the list. This fits an application whose server already renders its UI.
|
|
20
|
+
|
|
21
|
+
In the [HTML-app Todo](../html-app/examples/todo-ref.html), the form operates on a declared record array:
|
|
22
|
+
|
|
23
|
+
```html
|
|
24
|
+
<sym-context bind="$: APP/draft" pub-to="APP/draft">
|
|
25
|
+
<form action-data="APP/draft" action-reset="APP/draft"
|
|
26
|
+
bind="onsubmit: [append]APP/tasks">
|
|
27
|
+
<input required bind="value: title; oninput: [pub-to]title">
|
|
28
|
+
<button>Add task</button>
|
|
29
|
+
</form>
|
|
30
|
+
</sym-context>
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
This excerpt uses the `APP/draft` object and `APP/tasks` array declared in the complete Todo. Submission validates the form, appends a record and resets the draft. A collection renders the array through an Itemize template. Adding, editing and completing tasks can happen locally, with no request for replacement markup. The feature guide extends this with filtering and explicit browser saving.
|
|
34
|
+
|
|
35
|
+
## What HTML-app brings to the page
|
|
36
|
+
|
|
37
|
+
- **Shared reactive data.** Named contexts connect controls and views. Incoming bindings and explicit `pub-to` or `pub-map` publication describe data flow without application event handlers.
|
|
38
|
+
- **Local record operations.** Declarative actions create, edit, complete and remove records. Collection filters, search and sorting derive views while preserving the source array.
|
|
39
|
+
- **HTML-only component creation.** Declare your own custom element with `sym-component reg`, an inline template or `use-template`, and JSON defaults. Each instance has its own state and can use bindings and declarative actions, without a JavaScript class.
|
|
40
|
+
- **Portable HTML composition.** Assemble screens from imported HTML chunks, conditional sections and reusable templates. Chunks can bind to caller-provided data or contain components with their own state, so the same markup can serve different views. RAT keeps the templates portable; Symbiote provides the runtime behavior.
|
|
41
|
+
- **Explicit persistence.** Load JSON into a context, save selected fields in browser storage, or send them to a configured HTTP endpoint. Local edits, browser saves and server acknowledgments remain separate operations.
|
|
42
|
+
- **Markdown and compact AI output.** A host that loads HTML-app and preserves embedded HTML when rendering Markdown can combine prose and interactive components in one document. Agents can reuse declarative actions and templates, which can reduce output tokens spent on event handlers and state-management boilerplate.
|
|
43
|
+
- **Optional agent access.** WebMCP exposes declared UI actions through Symbiote's existing discovery and invocation APIs.
|
|
44
|
+
|
|
45
|
+
These features suit interactive editors, task lists and tools that need several views of locally editable data, including applications built against existing JSON APIs. A static server is enough for local interaction; shared or protected data still needs an appropriate backend.
|
|
46
|
+
|
|
47
|
+
## Where htmx fits
|
|
48
|
+
|
|
49
|
+
htmx is a natural fit when the server owns the application workflow and can return ready-to-display HTML. Its documented request triggers, targets, swap strategies and history integration let you extend that server-rendered experience from markup. See the [htmx documentation](https://htmx.org/docs/).
|
|
50
|
+
|
|
51
|
+
htmx also supports scripting, extensions and Web Component integration. The difference is whether your main interaction asks the server for HTML or updates reactive records already in the page.
|
|
52
|
+
|
|
53
|
+
Both still run JavaScript library code in the browser. HTML-app's HTML-only promise concerns application code: its supported declarative operations do not require handwritten JavaScript. Neither approach removes the backend's responsibility for authorization, validation or persistence.
|
|
54
|
+
|
|
55
|
+
For complete applications, start with the [HTML-app feature guide](../html-app/examples/full-app.html) or [htmx examples](https://htmx.org/examples/).
|
package/docs/lifecycle.md
CHANGED
|
@@ -31,6 +31,8 @@ class MyComponent extends Symbiote {
|
|
|
31
31
|
|
|
32
32
|
By default, components are destroyed when disconnected from DOM (after a 100ms delay). This delay allows synchronous DOM moves (e.g. list reordering) without triggering destruction.
|
|
33
33
|
|
|
34
|
+
After removing a component, call `component.destroy()` to finish its pending cleanup immediately. It reuses the normal teardown, ignores connected or uninitialized components, and is idempotent until reconnection. This is useful when a disposed view must release a named context before another view mounts. Ordinary disconnection retains its default delay.
|
|
35
|
+
|
|
34
36
|
If you do **NOT** plan to permanently remove your component from DOM or keep it just in memory, disable destruction:
|
|
35
37
|
```js
|
|
36
38
|
class MyComponent extends Symbiote {
|
package/docs/list-rendering.md
CHANGED
|
@@ -56,6 +56,14 @@ MyComponent.template = html`
|
|
|
56
56
|
|
|
57
57
|
> You can also use the `${{itemize: 'prop'}}` binding syntax if preferred — it produces the same result.
|
|
58
58
|
|
|
59
|
+
An anonymous item template can also be extracted into a `<template id="user-item">` in the containing root or document:
|
|
60
|
+
|
|
61
|
+
```html
|
|
62
|
+
<ul itemize="userList" use-template="#user-item"></ul>
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
The referenced template takes precedence over inline item markup. A registered `item-tag` continues to supply its own component template.
|
|
66
|
+
|
|
59
67
|
## List items
|
|
60
68
|
|
|
61
69
|
> **CRITICAL**: Items inside `itemize` are full Symbiote components with their own state scope.
|
|
@@ -219,7 +227,7 @@ More details in the [Animations](./animations.md) section.
|
|
|
219
227
|
|
|
220
228
|
## Keyed itemize processor
|
|
221
229
|
|
|
222
|
-
|
|
230
|
+
Use the optional keyed Itemize processor when record identity must survive updates and reordering:
|
|
223
231
|
```js
|
|
224
232
|
import { itemizeProcessor } from '@symbiotejs/symbiote/core/itemizeProcessor-keyed.js';
|
|
225
233
|
import { itemizeProcessor as defaultProcessor } from '@symbiotejs/symbiote/core/itemizeProcessor.js';
|
|
@@ -233,7 +241,7 @@ class BigList extends Symbiote {
|
|
|
233
241
|
}
|
|
234
242
|
```
|
|
235
243
|
|
|
236
|
-
|
|
244
|
+
Array records use a unique `id`, or `_KEY_` when no `id` is present. Object collections use their property keys. Every keyed record retains its element through reordering; duplicate or missing keys fail explicitly. Unkeyed arrays retain positional updates, and publishing the same array reference skips reconciliation. Leaving elements are inert and excluded from later reconciliation, so an exit animation cannot remove a newly added record.
|
|
237
245
|
|
|
238
246
|
## Lazy initialization (Massive lists)
|
|
239
247
|
|
package/docs/properties.md
CHANGED
|
@@ -40,9 +40,36 @@ class MyComponent extends Symbiote {
|
|
|
40
40
|
}
|
|
41
41
|
```
|
|
42
42
|
|
|
43
|
+
## Merging state
|
|
44
|
+
|
|
45
|
+
Assign an object to `$` to add or replace several state properties:
|
|
46
|
+
|
|
47
|
+
```js
|
|
48
|
+
const card = document.createElement('profile-card');
|
|
49
|
+
card.$ = { name: 'Alex', role: 'Reader' };
|
|
50
|
+
const state = card.$;
|
|
51
|
+
|
|
52
|
+
card.$ = { role: 'Editor', online: true };
|
|
53
|
+
// state === card.$; name remains 'Alex', role is 'Editor', online is added.
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
The component class must be registered before creating the element. Local state can be assigned before connection; missing `init$` defaults are added when it connects. Assignments preserve the proxy and omitted keys. The merge is shallow: a supplied object or array replaces that property's value by reference. Every supplied key notifies subscribers, even if a primitive value is unchanged. Keys are applied sequentially, so subscribers can observe intermediate values.
|
|
57
|
+
|
|
58
|
+
The setter uses `add$(stateObj, true)` and resolves shared (`*`), parent (`^`), and named (`CTX/key`) context keys. Named contexts must already exist. Select allowed keys from external data before assigning it; arbitrary keys can address other contexts or replace handler properties.
|
|
59
|
+
|
|
60
|
+
This also enables [binding an object to a child component's state](./templates.md#binding-an-object-to-child-state):
|
|
61
|
+
|
|
62
|
+
```js
|
|
63
|
+
ProfilePanel.template = html`
|
|
64
|
+
<profile-card ${{$: 'profile'}}></profile-card>
|
|
65
|
+
`;
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Publishing `profile` merges its fields into the child. This is a one-way binding. Mutating a nested field alone does not publish; reassign the parent property or call `notify('profile')` after changing it.
|
|
69
|
+
|
|
43
70
|
## Bulk updates
|
|
44
71
|
|
|
45
|
-
To
|
|
72
|
+
To update existing local properties while skipping unchanged string, number, and boolean values, use the `set$` method:
|
|
46
73
|
```js
|
|
47
74
|
class MyComponent extends Symbiote {
|
|
48
75
|
|
package/docs/pubsub.md
CHANGED
|
@@ -95,6 +95,9 @@ myDataCtx.multiPub({
|
|
|
95
95
|
|
|
96
96
|
### sub()
|
|
97
97
|
|
|
98
|
+
Subscriptions normally require an existing key. Pass a fourth argument `true` to wait for a key without creating it: `context.sub('lateField', handler, true, true)`. No initial callback runs until that field exists. The returned `remove()` method is idempotent. Component `this.sub()` uses this waiting behavior, supports a named context registered later, returns a remover, and releases pending subscriptions during teardown.
|
|
99
|
+
|
|
100
|
+
|
|
98
101
|
Subscribe to property changes.
|
|
99
102
|
|
|
100
103
|
| Argument | Type | Required | Description |
|
package/docs/routing.md
CHANGED
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
Symbiote.js has a built-in SPA routing solution based on the standard [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API).
|
|
4
4
|
|
|
5
|
+
For HTML-only applications, the optional foundation provides [`sym-router`](../html-app/README.md#declarative-routing), a declarative adapter to this same router.
|
|
6
|
+
|
|
5
7
|
> In 3.x, `AppRouter` is imported separately from the main package:
|
|
6
8
|
> ```js
|
|
7
9
|
> import { AppRouter } from '@symbiotejs/symbiote/core/AppRouter.js';
|
|
@@ -101,7 +103,7 @@ AppRouter.initRoutingCtx('R', {
|
|
|
101
103
|
### AppRouter.initRoutingCtx()
|
|
102
104
|
|
|
103
105
|
```js
|
|
104
|
-
initRoutingCtx(id, routingMap)
|
|
106
|
+
initRoutingCtx(id, routingMap, options)
|
|
105
107
|
// > PubSub instance
|
|
106
108
|
```
|
|
107
109
|
|
|
@@ -110,6 +112,8 @@ initRoutingCtx(id, routingMap)
|
|
|
110
112
|
| `id` | `String` | yes | Context ID |
|
|
111
113
|
| `routingMap` | `Object<string, RouteDescriptor>` | yes | Routing map |
|
|
112
114
|
|
|
115
|
+
Optional `options.signal` removes the context's route-event listener when aborted. An existing named context is reused without replacement; missing route-state fields are initialized. The context owner remains responsible for releasing its store and, when it owns the application router, calling `removePopstateListener()`.
|
|
116
|
+
|
|
113
117
|
`RouteDescriptor` type:
|
|
114
118
|
|
|
115
119
|
| Property | Type | Required | Description |
|
|
@@ -122,11 +126,13 @@ initRoutingCtx(id, routingMap)
|
|
|
122
126
|
|
|
123
127
|
### AppRouter.navigate()
|
|
124
128
|
|
|
125
|
-
Navigate and dispatch route change event:
|
|
129
|
+
Navigate and dispatch the route change event. The returned promise resolves after native guards and loading complete:
|
|
126
130
|
```js
|
|
127
|
-
AppRouter.navigate('user', { id: '42' });
|
|
131
|
+
await AppRouter.navigate('user', { id: '42' });
|
|
128
132
|
```
|
|
129
133
|
|
|
134
|
+
URL options are copied before path substitution. Query values are encoded and decoded. A newer navigation or map configuration prevents an obsolete asynchronous guard/loader from publishing over current state.
|
|
135
|
+
|
|
130
136
|
> **Migration note**: `applyRoute()` from 2.x has been renamed to `navigate()` in 3.x.
|
|
131
137
|
|
|
132
138
|
### AppRouter.reflect()
|
|
@@ -145,11 +151,14 @@ AppRouter.notify();
|
|
|
145
151
|
|
|
146
152
|
### AppRouter.readAddressBar()
|
|
147
153
|
|
|
148
|
-
Read and parse the current URL:
|
|
154
|
+
Read and parse the current URL, or supply a URL/location-like object without changing browser history:
|
|
149
155
|
```js
|
|
150
156
|
let { route, options } = AppRouter.readAddressBar();
|
|
157
|
+
let target = AppRouter.readAddressBar(new URL(link.href));
|
|
151
158
|
```
|
|
152
159
|
|
|
160
|
+
Malformed percent encoding produces an unmatched route instead of throwing.
|
|
161
|
+
|
|
153
162
|
### AppRouter.beforeRoute()
|
|
154
163
|
|
|
155
164
|
Register a route guard. Returns an unsubscribe function:
|
|
@@ -167,6 +176,8 @@ AppRouter.setRoutingMap({
|
|
|
167
176
|
});
|
|
168
177
|
```
|
|
169
178
|
|
|
179
|
+
Pass `true` as the second argument to replace the map and reset route defaults and path/query mode. Patterns compile before the new map takes effect, so an invalid pattern leaves the previous configuration intact. The default behavior remains additive.
|
|
180
|
+
|
|
170
181
|
### AppRouter.setSeparator()
|
|
171
182
|
|
|
172
183
|
Set custom separator for query-string mode (default: `&`):
|
package/docs/security.md
CHANGED
|
@@ -1,25 +1,43 @@
|
|
|
1
1
|
# Security
|
|
2
2
|
|
|
3
|
-
##
|
|
3
|
+
## Templates and untrusted data
|
|
4
|
+
|
|
5
|
+
Treat component templates, binding maps, and handler names as application code. The `html` helper concatenates string and number interpolations without escaping. Neither it nor the template renderer sanitizes HTML.
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
Display external text through a state binding:
|
|
6
8
|
|
|
7
|
-
Template `innerHTML` writes use a Trusted Types policy when the API is available:
|
|
8
9
|
```js
|
|
9
|
-
|
|
10
|
-
|
|
10
|
+
import Symbiote, { html } from '@symbiotejs/symbiote';
|
|
11
|
+
|
|
12
|
+
class MessageText extends Symbiote {
|
|
13
|
+
init$ = { message: '' };
|
|
14
|
+
}
|
|
15
|
+
MessageText.template = html`<p ${{textContent: 'message'}}></p>`;
|
|
16
|
+
MessageText.reg('message-text');
|
|
17
|
+
|
|
18
|
+
const message = document.createElement('message-text');
|
|
19
|
+
message.$ = { message: '<b>This is displayed as text.</b>' };
|
|
20
|
+
document.body.append(message);
|
|
11
21
|
```
|
|
12
22
|
|
|
23
|
+
`textContent` and `{{prop}}` text-node bindings insert text without interpreting it as HTML. Use `textContent` for hydratable SSR markup. Do not interpolate external text directly into a template or bind it to `innerHTML`, event attributes, scripts, or style text. Validate URL schemes and destinations before binding values to URL properties such as `href` or `src`.
|
|
24
|
+
|
|
25
|
+
If the application needs rich HTML, sanitize it through a reviewed HTML sanitization path appropriate to its target browsers and CSP before insertion. Keep that content outside Symbiote template processing: an HTML sanitizer does not necessarily understand Symbiote bindings, custom element behavior, or handler references.
|
|
26
|
+
|
|
27
|
+
State merging accepts arbitrary keys, including context prefixes and handler properties. Map external records to an explicit set of application fields before assigning `$`; do not spread an unvalidated API response or parsed object into component state.
|
|
28
|
+
|
|
29
|
+
## Trusted Types
|
|
30
|
+
|
|
31
|
+
Symbiote.js uses a policy named `symbiote` for its template `innerHTML` writes when [Trusted Types](https://developer.mozilla.org/en-US/docs/Web/API/Trusted_Types_API) is available. The policy passes the HTML through unchanged; it provides a Trusted Types value, not sanitization or a general XSS defense.
|
|
32
|
+
|
|
13
33
|
### CSP configuration
|
|
14
34
|
|
|
15
|
-
|
|
35
|
+
Allow this policy alongside the application's other required policies:
|
|
16
36
|
```
|
|
17
37
|
Content-Security-Policy: require-trusted-types-for 'script'; trusted-types symbiote
|
|
18
38
|
```
|
|
19
39
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
> No sanitization is performed — templates are developer-authored, not user input. The policy exists to satisfy the Trusted Types API requirement.
|
|
40
|
+
These are Trusted Types directives, not a complete CSP. Keep the application's `script-src`, `style-src`, and other restrictions. Only developer-controlled templates should reach this policy. Direct DOM property bindings, including `innerHTML`, do not pass through the template policy and must meet the destination's own requirements. Do not disable Trusted Types or add permissive policy rules to accept untrusted markup.
|
|
23
41
|
|
|
24
42
|
## CSP nonce for SSR styles
|
|
25
43
|
|
|
@@ -27,9 +45,10 @@ When using [SSR](./ssr.md), component styles (`rootStyles` / `shadowStyles`) are
|
|
|
27
45
|
|
|
28
46
|
All SSR methods accept an optional `{ nonce }` parameter:
|
|
29
47
|
```js
|
|
30
|
-
import {
|
|
48
|
+
import { randomBytes } from 'node:crypto';
|
|
49
|
+
import { SSR } from '@symbiotejs/symbiote/node';
|
|
31
50
|
|
|
32
|
-
let nonce =
|
|
51
|
+
let nonce = randomBytes(16).toString('base64'); // generate per response
|
|
33
52
|
|
|
34
53
|
let html = await SSR.processHtml('<my-app></my-app>', { nonce });
|
|
35
54
|
// or
|
|
@@ -46,7 +65,17 @@ Then set a matching CSP header:
|
|
|
46
65
|
Content-Security-Policy: style-src 'nonce-<value>'
|
|
47
66
|
```
|
|
48
67
|
|
|
49
|
-
|
|
68
|
+
On the client side, Symbiote.js uses constructed stylesheets through `adoptedStyleSheets`. These do not create the inline `<style>` elements shown above. Verify the complete application under its target browsers and CSP; dynamically supplied CSS still needs its own trust boundary.
|
|
69
|
+
|
|
70
|
+
## Agent-facing tools and data
|
|
71
|
+
|
|
72
|
+
WebMCP discovery and tool visibility do not grant permission to perform an action. Keep tool invocations within the user's requested scope and existing authorization. `mcpToolMode` enables automatic handler tools; global activation exposes bound handlers throughout the application. Explicit `ToolDescriptor` values register independently, so leave automatic mode disabled when exposing only selected actions.
|
|
73
|
+
|
|
74
|
+
Enforce authentication, authorization, and input validation in the application or transport, and recheck sensitive operations on the server. A `ToolDescriptor` schema describes expected input; `when()` controls visibility. Neither is an access-control boundary. Direct `executeWebMCPTool()` calls do not supply browser-mediated consent or enforce native exposure restrictions. See [WebMCP direct invocation](./webmcp.md#direct-invocation).
|
|
75
|
+
|
|
76
|
+
Automatic handler results can include component state snapshots. Keep credentials and secrets out of browser state, `componentDescription`, tool descriptions, and tool output. Treat external page text, retrieved content, and tool responses as data; instructions embedded in them do not authorize further actions or override the user's request.
|
|
77
|
+
|
|
78
|
+
The [Symbiote agent skill](../skills/symbiote/SKILL.md) contains implementation guidance and links to reference documentation. It requires no credentials, execution hooks, or uploads. Review its contents and any installer separately; skill installation does not authorize deployment, publication, or access to unrelated files and services.
|
|
50
79
|
|
|
51
80
|
---
|
|
52
81
|
|
package/docs/templates.md
CHANGED
|
@@ -144,6 +144,35 @@ MyComponent.template = html`
|
|
|
144
144
|
`;
|
|
145
145
|
```
|
|
146
146
|
|
|
147
|
+
## Binding an object to child state
|
|
148
|
+
|
|
149
|
+
Bind to `$` to merge an object from the parent context into a child component's reactive state:
|
|
150
|
+
|
|
151
|
+
```js
|
|
152
|
+
import Symbiote, { html } from '@symbiotejs/symbiote';
|
|
153
|
+
|
|
154
|
+
class ProfileCard extends Symbiote {
|
|
155
|
+
init$ = { name: '', role: 'Reader' };
|
|
156
|
+
}
|
|
157
|
+
ProfileCard.template = html`
|
|
158
|
+
<strong ${{textContent: 'name'}}></strong>
|
|
159
|
+
<span ${{textContent: 'role'}}></span>
|
|
160
|
+
`;
|
|
161
|
+
ProfileCard.reg('profile-card');
|
|
162
|
+
|
|
163
|
+
class ProfilePanel extends Symbiote {
|
|
164
|
+
init$ = { profile: { name: 'Alex' } };
|
|
165
|
+
}
|
|
166
|
+
ProfilePanel.template = html`
|
|
167
|
+
<profile-card ${{$: 'profile'}}></profile-card>
|
|
168
|
+
`;
|
|
169
|
+
ProfilePanel.reg('profile-panel');
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
The equivalent plain HTML binding is `<profile-card bind="$: profile"></profile-card>`. Register the child class before mounting the parent. Symbiote defers the initial assignment until the child initializes, so it displays `Alex` with its default role `Reader`.
|
|
173
|
+
|
|
174
|
+
After mounting, `panel.$.profile = { role: 'Editor' }` updates the child's role and preserves its name. New keys are registered, and the child's `$` proxy remains the same object. Child changes do not publish back to the parent. Object mutations alone do not notify; publish the parent property again or call `panel.notify('profile')`. See [state merging](./properties.md#merging-state) for notification and context rules.
|
|
175
|
+
|
|
147
176
|
## Binding to HTML attributes
|
|
148
177
|
|
|
149
178
|
To bind a property to an element's attribute, use the `@` prefix:
|
|
@@ -0,0 +1,203 @@
|
|
|
1
|
+
import Symbiote, { css } from '../core/Symbiote.js';
|
|
2
|
+
import { DICT } from '../core/dictionary.js';
|
|
3
|
+
import { ActionBindings, actionProcessor } from './actions.js';
|
|
4
|
+
import { PubMap } from './pub-map.js';
|
|
5
|
+
import { declarationProcessor } from './declarations.js';
|
|
6
|
+
import { initialDataProcessor, isDataKey, readInitialData, readTemplateData, rememberDefaults } from './initial-data.js';
|
|
7
|
+
|
|
8
|
+
export class BaseClass extends Symbiote {
|
|
9
|
+
static observedAttributes = [
|
|
10
|
+
'pub-map',
|
|
11
|
+
];
|
|
12
|
+
actionBindings = new ActionBindings(this);
|
|
13
|
+
outgoingBindings = new PubMap(this);
|
|
14
|
+
processInnerHtml = true;
|
|
15
|
+
allowCustomTemplate = true;
|
|
16
|
+
#scheduled = false;
|
|
17
|
+
#connecting = false;
|
|
18
|
+
/** @type {string | undefined} */
|
|
19
|
+
#markup;
|
|
20
|
+
#rebuild = false;
|
|
21
|
+
#seeded = false;
|
|
22
|
+
/** @type {Record<string, unknown>} */
|
|
23
|
+
#snapshot = {};
|
|
24
|
+
|
|
25
|
+
// Native Itemize uses this class for its generated item owners.
|
|
26
|
+
get Symbiote() {
|
|
27
|
+
return BaseClass;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/** @param {string | null} _value */
|
|
31
|
+
set 'pub-map'(_value) {
|
|
32
|
+
this.outgoingBindings.refresh();
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
connectedCallback() {
|
|
36
|
+
this.seedDefaults();
|
|
37
|
+
if (globalThis.__SYMBIOTE_SSR) {
|
|
38
|
+
this.connectFoundation();
|
|
39
|
+
return;
|
|
40
|
+
}
|
|
41
|
+
if (this.#scheduled) { return; }
|
|
42
|
+
this.#scheduled = true;
|
|
43
|
+
queueMicrotask(() => {
|
|
44
|
+
this.#scheduled = false;
|
|
45
|
+
this.connectFoundation();
|
|
46
|
+
});
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
connectFoundation() {
|
|
50
|
+
if (!this.isConnected || this.#connecting) { return; }
|
|
51
|
+
this.#connecting = true;
|
|
52
|
+
try {
|
|
53
|
+
// All foundation tags can upgrade before nested owners initialize.
|
|
54
|
+
let parent = this.parentNode;
|
|
55
|
+
while (parent) {
|
|
56
|
+
if (parent instanceof BaseClass) {
|
|
57
|
+
parent.connectFoundation();
|
|
58
|
+
break;
|
|
59
|
+
}
|
|
60
|
+
parent = parent.parentNode || (typeof ShadowRoot !== 'undefined' && parent instanceof ShadowRoot ? parent.host : null);
|
|
61
|
+
}
|
|
62
|
+
// An ancestor may remove this child while deciding conditional content.
|
|
63
|
+
if (!this.isConnected) { return; }
|
|
64
|
+
if (this.#rebuild) { this.connectedOnce = false; }
|
|
65
|
+
if (!this.connectedOnce) { this.prepare(); }
|
|
66
|
+
super.connectedCallback();
|
|
67
|
+
this.actionBindings.connect();
|
|
68
|
+
this.outgoingBindings.connect();
|
|
69
|
+
} finally {
|
|
70
|
+
this.#connecting = false;
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
seedDefaults() {
|
|
75
|
+
if (this.#seeded) { return; }
|
|
76
|
+
if (this.#markup === undefined) { this.#markup = this.innerHTML; }
|
|
77
|
+
let root = this.#rebuild ? this.authoredContent() : this;
|
|
78
|
+
let defaults = {
|
|
79
|
+
...readTemplateData(this),
|
|
80
|
+
...readInitialData(root),
|
|
81
|
+
};
|
|
82
|
+
rememberDefaults(this.localCtx, defaults);
|
|
83
|
+
this.init$ = {
|
|
84
|
+
...defaults,
|
|
85
|
+
...this.init$,
|
|
86
|
+
...this.#snapshot,
|
|
87
|
+
};
|
|
88
|
+
for (let [
|
|
89
|
+
key,
|
|
90
|
+
value,
|
|
91
|
+
] of Object.entries(this.init$)) {
|
|
92
|
+
if (isDataKey(key)) { this.localCtx.add(key, value); }
|
|
93
|
+
}
|
|
94
|
+
this.#seeded = true;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
prepare() {
|
|
98
|
+
this.seedDefaults();
|
|
99
|
+
this.templateProcessors.add(declarationProcessor);
|
|
100
|
+
this.templateProcessors.add(initialDataProcessor);
|
|
101
|
+
this.templateProcessors.add(actionProcessor);
|
|
102
|
+
let parsing = this.getAttribute('process-inner-html');
|
|
103
|
+
if (parsing !== null) {
|
|
104
|
+
if (![
|
|
105
|
+
'true',
|
|
106
|
+
'false',
|
|
107
|
+
].includes(parsing)) {
|
|
108
|
+
throw new TypeError('process-inner-html must be true or false.');
|
|
109
|
+
}
|
|
110
|
+
this.processInnerHtml = parsing === 'true';
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
authoredContent() {
|
|
115
|
+
let template = this.ownerDocument.createElement('template');
|
|
116
|
+
template.innerHTML = this.#markup ?? '';
|
|
117
|
+
return /** @type {DocumentFragment} */ (template.content.cloneNode(true));
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
/**
|
|
121
|
+
* @param {string | DocumentFragment} [template]
|
|
122
|
+
* @param {boolean} [shadow]
|
|
123
|
+
*/
|
|
124
|
+
render(template, shadow) {
|
|
125
|
+
this.restoreContent();
|
|
126
|
+
super.render(template, shadow);
|
|
127
|
+
this.actionBindings.connect();
|
|
128
|
+
this.outgoingBindings.connect();
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
restoreContent() {
|
|
132
|
+
if (this.#rebuild) {
|
|
133
|
+
this.#rebuild = false;
|
|
134
|
+
this.ref = Object.create(null);
|
|
135
|
+
this.replaceChildren(this.authoredContent());
|
|
136
|
+
}
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
/**
|
|
140
|
+
* @param {Record<string, unknown>} values
|
|
141
|
+
* @param {boolean} [force]
|
|
142
|
+
*/
|
|
143
|
+
set$(values, force = false) {
|
|
144
|
+
let itemUpdate = Reflect.has(this, DICT.MCP_ITEM_INDEX_KEY) && Object.keys(values).some(isDataKey);
|
|
145
|
+
if (itemUpdate) {
|
|
146
|
+
this.actionBindings.invalidate();
|
|
147
|
+
}
|
|
148
|
+
// An incoming record also resets invalid DOM drafts absent from state.
|
|
149
|
+
super.set$(values, force || itemUpdate);
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
/**
|
|
153
|
+
* @param {Record<string, unknown>} values
|
|
154
|
+
* @param {boolean} [rewrite]
|
|
155
|
+
*/
|
|
156
|
+
add$(values, rewrite = false) {
|
|
157
|
+
if (Reflect.has(this, DICT.MCP_ITEM_INDEX_KEY) && Object.keys(values).some(isDataKey)) {
|
|
158
|
+
this.actionBindings.invalidate();
|
|
159
|
+
}
|
|
160
|
+
super.add$(values, rewrite);
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
disconnectedCallback() {
|
|
164
|
+
this.actionBindings.disconnect();
|
|
165
|
+
this.outgoingBindings.disconnect();
|
|
166
|
+
super.disconnectedCallback();
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
destroyCallback() {
|
|
170
|
+
this.actionBindings.destroy();
|
|
171
|
+
this.outgoingBindings.disconnect();
|
|
172
|
+
// Native teardown removes subscriptions. Reconnect reprocesses authored RAT,
|
|
173
|
+
// retaining state rather than trying to reuse nodes with removed bindings.
|
|
174
|
+
this.#snapshot = Object.fromEntries(Object.entries(this.localCtx.store).filter(([
|
|
175
|
+
key,
|
|
176
|
+
]) => !key.startsWith('__htmlApp')));
|
|
177
|
+
this.#rebuild = true;
|
|
178
|
+
this.#seeded = false;
|
|
179
|
+
super.destroyCallback();
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
export default BaseClass;
|
|
184
|
+
|
|
185
|
+
BaseClass.rootStyles = css`
|
|
186
|
+
sym-component,
|
|
187
|
+
sym-context,
|
|
188
|
+
sym-collection,
|
|
189
|
+
sym-conditional,
|
|
190
|
+
sym-import,
|
|
191
|
+
sym-router {
|
|
192
|
+
display: contents;
|
|
193
|
+
}
|
|
194
|
+
sym-component[hidden],
|
|
195
|
+
sym-context[hidden],
|
|
196
|
+
sym-collection[hidden],
|
|
197
|
+
sym-conditional[hidden],
|
|
198
|
+
sym-import[hidden],
|
|
199
|
+
sym-router[hidden],
|
|
200
|
+
sym-component[reg] {
|
|
201
|
+
display: none;
|
|
202
|
+
}
|
|
203
|
+
`;
|