@symbiotejs/symbiote 3.9.0 → 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.
Files changed (131) hide show
  1. package/README.md +12 -0
  2. package/core/AppRouter.js +97 -58
  3. package/core/PubSub.js +42 -11
  4. package/core/Symbiote.js +70 -46
  5. package/core/itemizeProcessor-keyed.js +88 -188
  6. package/core/itemizeProcessor.js +1 -12
  7. package/core/itemizeSetup.js +26 -3
  8. package/core/ownElements.js +1 -4
  9. package/core/resolveTemplate.js +12 -0
  10. package/core/tpl-processors.js +1 -2
  11. package/docs/README.md +2 -0
  12. package/docs/html-app-vs-htmx.md +55 -0
  13. package/docs/lifecycle.md +2 -0
  14. package/docs/list-rendering.md +10 -2
  15. package/docs/pubsub.md +3 -0
  16. package/docs/routing.md +15 -4
  17. package/html-app/BaseClass.js +203 -0
  18. package/html-app/README.md +369 -0
  19. package/html-app/action-data.js +168 -0
  20. package/html-app/actions.js +366 -0
  21. package/html-app/collection-actions.js +104 -0
  22. package/html-app/collection-data.js +234 -0
  23. package/html-app/collection-items.js +45 -0
  24. package/html-app/conditions.js +42 -0
  25. package/html-app/context-data.js +185 -0
  26. package/html-app/context-requests.js +374 -0
  27. package/html-app/context-storage.js +376 -0
  28. package/html-app/declarations.js +55 -0
  29. package/html-app/examples/assets/actions.html +56 -0
  30. package/html-app/examples/assets/collections.html +72 -0
  31. package/html-app/examples/assets/components.html +25 -0
  32. package/html-app/examples/assets/conditional.html +29 -0
  33. package/html-app/examples/assets/data.html +31 -0
  34. package/html-app/examples/assets/guide.html +4 -0
  35. package/html-app/examples/assets/imports.html +11 -0
  36. package/html-app/examples/assets/not-found.html +4 -0
  37. package/html-app/examples/assets/routes.json +58 -0
  38. package/html-app/examples/assets/routing.html +27 -0
  39. package/html-app/examples/assets/state.html +32 -0
  40. package/html-app/examples/assets/storage.html +28 -0
  41. package/html-app/examples/assets/tasks.json +25 -0
  42. package/html-app/examples/full-app.html +147 -0
  43. package/html-app/examples/todo-ref.html +37 -0
  44. package/html-app/fetch-source.js +147 -0
  45. package/html-app/fragment-content.js +29 -0
  46. package/html-app/fragment-source.js +169 -0
  47. package/html-app/index.js +34 -0
  48. package/html-app/initial-data.js +88 -0
  49. package/html-app/pub-map.js +93 -0
  50. package/html-app/router-data.js +50 -0
  51. package/html-app/router-navigation.js +70 -0
  52. package/html-app/storage-revisions.js +130 -0
  53. package/html-app/sym-collection.js +142 -0
  54. package/html-app/sym-component.js +20 -0
  55. package/html-app/sym-conditional.js +141 -0
  56. package/html-app/sym-context.js +176 -0
  57. package/html-app/sym-import.js +218 -0
  58. package/html-app/sym-router.js +107 -0
  59. package/package.json +18 -6
  60. package/scripts/check-html-app-package.js +117 -0
  61. package/scripts/check-html-app-size.js +91 -0
  62. package/scripts/update-exports.js +4 -0
  63. package/skills/symbiote/SKILL.md +64 -15
  64. package/skills/symbiote/agents/openai.yaml +1 -1
  65. package/types/core/AppRouter.d.ts +13 -4
  66. package/types/core/AppRouter.d.ts.map +1 -1
  67. package/types/core/PubSub.d.ts +1 -1
  68. package/types/core/PubSub.d.ts.map +1 -1
  69. package/types/core/Symbiote.d.ts +4 -1
  70. package/types/core/Symbiote.d.ts.map +1 -1
  71. package/types/core/itemizeProcessor-keyed.d.ts.map +1 -1
  72. package/types/core/itemizeProcessor.d.ts.map +1 -1
  73. package/types/core/itemizeSetup.d.ts +1 -0
  74. package/types/core/itemizeSetup.d.ts.map +1 -1
  75. package/types/core/ownElements.d.ts +1 -1
  76. package/types/core/ownElements.d.ts.map +1 -1
  77. package/types/core/resolveTemplate.d.ts +2 -0
  78. package/types/core/resolveTemplate.d.ts.map +1 -0
  79. package/types/core/tpl-processors.d.ts.map +1 -1
  80. package/types/html-app/BaseClass.d.ts +24 -0
  81. package/types/html-app/BaseClass.d.ts.map +1 -0
  82. package/types/html-app/action-data.d.ts +15 -0
  83. package/types/html-app/action-data.d.ts.map +1 -0
  84. package/types/html-app/actions.d.ts +104 -0
  85. package/types/html-app/actions.d.ts.map +1 -0
  86. package/types/html-app/collection-actions.d.ts +12 -0
  87. package/types/html-app/collection-actions.d.ts.map +1 -0
  88. package/types/html-app/collection-data.d.ts +13 -0
  89. package/types/html-app/collection-data.d.ts.map +1 -0
  90. package/types/html-app/collection-items.d.ts +7 -0
  91. package/types/html-app/collection-items.d.ts.map +1 -0
  92. package/types/html-app/conditions.d.ts +5 -0
  93. package/types/html-app/conditions.d.ts.map +1 -0
  94. package/types/html-app/context-data.d.ts +31 -0
  95. package/types/html-app/context-data.d.ts.map +1 -0
  96. package/types/html-app/context-requests.d.ts +97 -0
  97. package/types/html-app/context-requests.d.ts.map +1 -0
  98. package/types/html-app/context-storage.d.ts +102 -0
  99. package/types/html-app/context-storage.d.ts.map +1 -0
  100. package/types/html-app/declarations.d.ts +3 -0
  101. package/types/html-app/declarations.d.ts.map +1 -0
  102. package/types/html-app/fetch-source.d.ts +23 -0
  103. package/types/html-app/fetch-source.d.ts.map +1 -0
  104. package/types/html-app/fragment-content.d.ts +6 -0
  105. package/types/html-app/fragment-content.d.ts.map +1 -0
  106. package/types/html-app/fragment-source.d.ts +14 -0
  107. package/types/html-app/fragment-source.d.ts.map +1 -0
  108. package/types/html-app/index.d.ts +9 -0
  109. package/types/html-app/index.d.ts.map +1 -0
  110. package/types/html-app/initial-data.d.ts +8 -0
  111. package/types/html-app/initial-data.d.ts.map +1 -0
  112. package/types/html-app/pub-map.d.ts +19 -0
  113. package/types/html-app/pub-map.d.ts.map +1 -0
  114. package/types/html-app/router-data.d.ts +4 -0
  115. package/types/html-app/router-data.d.ts.map +1 -0
  116. package/types/html-app/router-navigation.d.ts +3 -0
  117. package/types/html-app/router-navigation.d.ts.map +1 -0
  118. package/types/html-app/storage-revisions.d.ts +11 -0
  119. package/types/html-app/storage-revisions.d.ts.map +1 -0
  120. package/types/html-app/sym-collection.d.ts +16 -0
  121. package/types/html-app/sym-collection.d.ts.map +1 -0
  122. package/types/html-app/sym-component.d.ts +5 -0
  123. package/types/html-app/sym-component.d.ts.map +1 -0
  124. package/types/html-app/sym-conditional.d.ts +10 -0
  125. package/types/html-app/sym-conditional.d.ts.map +1 -0
  126. package/types/html-app/sym-context.d.ts +16 -0
  127. package/types/html-app/sym-context.d.ts.map +1 -0
  128. package/types/html-app/sym-import.d.ts +19 -0
  129. package/types/html-app/sym-import.d.ts.map +1 -0
  130. package/types/html-app/sym-router.d.ts +12 -0
  131. package/types/html-app/sym-router.d.ts.map +1 -0
@@ -1,217 +1,117 @@
1
1
  import { animateOut } from './animateOut.js';
2
2
  import { warnMsg } from './warn.js';
3
- import { setupItemize } from './itemizeSetup.js';
3
+ import { setupItemize, setItemWebMCPMetadata } from './itemizeSetup.js';
4
4
 
5
5
  /**
6
- * Optimized itemize template processor.
7
- *
8
- * Drop-in replacement for the default itemizeProcessor with:
9
- * - Reference-equality fast paths for append, truncate, and no-op
10
- * - Key-based reconciliation (using `_KEY_` or `id` properties) for efficient reordering
11
- * - Skip-if-same optimization for index-based patching
12
- *
13
- * Usage:
14
- * ```js
15
- * import { itemizeProcessor } from '@symbiotejs/symbiote/core/itemizeProcessor-keyed.js';
16
- * import { itemizeProcessor as defaultProcessor } from '@symbiotejs/symbiote/core/itemizeProcessor.js';
17
- *
18
- * class MyList extends Symbiote {
19
- * constructor() {
20
- * super();
21
- * // Swap default for keyed version
22
- * this.templateProcessors.delete(defaultProcessor);
23
- * this.templateProcessors = new Set([itemizeProcessor, ...this.templateProcessors]);
24
- * }
25
- * }
26
- * ```
27
- *
6
+ * Optional Itemize processor with stable keyed identity.
7
+ * Keyed records always keep their element, including complete reversals.
28
8
  * @template {import('./Symbiote.js').Symbiote} T
29
9
  * @param {DocumentFragment} fr
30
10
  * @param {T} fnCtx
31
11
  */
32
12
  export function itemizeProcessor(fr, fnCtx) {
33
- setupItemize(fr, fnCtx, ({ el, itemClass, repeatDataKey, clientSSR, isLazy }) => {
34
- /** @type {*[]} */
35
- let prevData = [];
13
+ setupItemize(fr, fnCtx, ({
14
+ el,
15
+ itemClass,
16
+ repeatDataKey,
17
+ clientSSR,
18
+ isLazy,
19
+ }) => {
20
+ /** @type {any[]} */
21
+ let previous = [];
22
+ let hydrating = clientSSR;
23
+ /** @type {any[]} */
24
+ let active = [
25
+ ...el.children,
26
+ ];
36
27
 
37
28
  fnCtx.sub(repeatDataKey, (data) => {
38
- if (!data) {
39
- while (el.firstChild) {
40
- el.firstChild.remove();
29
+ /** @type {any[]} */
30
+ let items = [];
31
+ if (data) {
32
+ if (Array.isArray(data)) {
33
+ items = data;
34
+ } else if (data.constructor === Object) {
35
+ items = Object.entries(data).map(([
36
+ key,
37
+ value,
38
+ ]) => ({
39
+ ...value,
40
+ _KEY_: key,
41
+ }));
42
+ } else {
43
+ warnMsg(16, fnCtx.localName, typeof data, data);
44
+ return;
41
45
  }
42
- prevData = [];
43
- return;
44
46
  }
45
-
46
- /** @type {*[]} */
47
- let items;
48
- if (data.constructor === Array) {
49
- items = data;
50
- } else if (data.constructor === Object) {
51
- items = [];
52
- for (let itemKey in data) {
53
- let init = data[itemKey];
54
- Object.defineProperty(init, '_KEY_', {
55
- value: itemKey,
56
- enumerable: true,
57
- });
58
- items.push(init);
59
- }
60
- } else {
61
- warnMsg(16, fnCtx.localName, typeof data, data);
47
+ if (items === previous) {
62
48
  return;
63
49
  }
64
-
65
- let children = el.children;
66
- let prevLen = children.length;
67
- let newLen = items.length;
68
-
69
- // ── Fast path: no-op (same array reference) ──
70
- if (data === prevData || items === prevData) {
71
- return;
50
+ let keyProp = items[0]?.id !== undefined && Array.isArray(data) ? 'id'
51
+ : items[0]?._KEY_ !== undefined ? '_KEY_' : null;
52
+ let keys = keyProp ? items.map((item) => item[keyProp]) : [];
53
+ if (keyProp && (keys.some((key) => key === undefined) || new Set(keys).size !== keys.length)) {
54
+ throw new TypeError('Keyed Itemize requires unique keys on every record.');
72
55
  }
73
-
74
- // ── Fast path: simple truncate (tail removal) ──
75
- if (newLen < prevLen && newLen > 0) {
76
- if (items[0] === prevData[0] && items[newLen - 1] === prevData[newLen - 1]) {
77
- for (let i = prevLen - 1; i >= newLen; i--) {
78
- animateOut(children[i]);
79
- }
80
- prevData = items;
81
- return;
82
- }
56
+ let byKey = new Map();
57
+ if (keyProp) {
58
+ previous.forEach((item, index) => byKey.set(item[keyProp], index));
83
59
  }
84
-
85
- // ── Fast path: simple append ──
86
- if (newLen > prevLen && prevLen > 0) {
87
- if (items[0] === prevData[0] && items[prevLen - 1] === prevData[prevLen - 1]) {
88
- let fragment = document.createDocumentFragment();
89
- for (let i = prevLen; i < newLen; i++) {
90
- let repeatItem = new itemClass();
91
- if (isLazy) {
92
- repeatItem.lazyMode = true;
93
- }
94
- Object.assign((repeatItem?.init$ || repeatItem), items[i]);
95
- fragment.appendChild(repeatItem);
96
- }
97
- el.appendChild(fragment);
98
- prevData = items;
99
- return;
100
- }
101
- }
102
-
103
- // ── Full reconciliation ──
104
- let keyProp = items[0]?._KEY_ !== undefined ? '_KEY_' : (items[0]?.id !== undefined ? 'id' : null);
105
-
106
- if (keyProp && prevLen > 0) {
107
- /** @type {Map<*, number>} */
108
- let prevKeyToIdx = new Map();
109
- for (let i = 0; i < prevLen; i++) {
110
- let key = prevData[i]?.[keyProp];
111
- if (key !== undefined) {
112
- prevKeyToIdx.set(key, i);
113
- }
114
- }
115
-
116
- // Count out-of-order moves to decide strategy
117
- let movesNeeded = 0;
118
- let lastReusedIdx = -1;
119
-
120
- for (let i = 0; i < newLen; i++) {
121
- let prevIdx = prevKeyToIdx.get(items[i][keyProp]);
122
- if (prevIdx !== undefined) {
123
- if (prevIdx < lastReusedIdx) {
124
- movesNeeded++;
125
- }
126
- lastReusedIdx = prevIdx;
127
- }
128
- }
129
-
130
- // DOM reorder only when few moves needed; otherwise patch in-place
131
- if (movesNeeded < newLen * 0.3) {
132
- let newChildren = [];
133
- let toRemove = new Set(prevKeyToIdx.keys());
134
-
135
- for (let i = 0; i < newLen; i++) {
136
- let item = items[i];
137
- let key = item[keyProp];
138
- let prevIdx = prevKeyToIdx.get(key);
139
-
140
- if (prevIdx !== undefined) {
141
- let existing = children[prevIdx];
142
- if (item !== prevData[prevIdx]) {
143
- // @ts-expect-error
144
- if (existing.set$) {
145
- // @ts-expect-error
146
- existing.set$(item);
147
- } else {
148
- for (let k in item) {
149
- existing[k] = item[k];
150
- }
151
- }
152
- }
153
- toRemove.delete(key);
154
- newChildren.push(existing);
155
- } else {
156
- let repeatItem = new itemClass();
157
- if (isLazy) {
158
- repeatItem.lazyMode = true;
159
- }
160
- Object.assign((repeatItem?.init$ || repeatItem), item);
161
- newChildren.push(repeatItem);
162
- }
163
- }
164
-
165
- let removeEls = [...toRemove].map((key) => children[prevKeyToIdx.get(key)]);
166
- for (let el of removeEls) {
167
- animateOut(el);
168
- }
169
-
170
- for (let i = 0; i < newChildren.length; i++) {
171
- if (children[i] !== newChildren[i]) {
172
- el.insertBefore(newChildren[i], children[i] || null);
173
- }
174
- }
175
-
176
- prevData = items;
177
- return;
178
- }
179
- }
180
-
181
- // ── Index-based patching (fallback, same as default + skip-if-same) ──
182
- let fragment;
183
- for (let i = 0; i < newLen; i++) {
184
- if (i < prevLen) {
185
- if (items[i] !== prevData[i]) {
186
- let child = children[i];
187
- // @ts-expect-error
60
+ let retained = new Set();
61
+ let next = items.map((item, index) => {
62
+ let previousIndex = hydrating ? index : keyProp ? byKey.get(item[keyProp]) : index;
63
+ let child = previousIndex === undefined ? null : active[previousIndex];
64
+ if (child) {
65
+ retained.add(child);
66
+ if (hydrating) {
67
+ child.ssrMode = true;
68
+ child.$ = item;
69
+ } else if (item !== previous[previousIndex]) {
188
70
  if (child.set$) {
189
- // @ts-expect-error
190
- child.set$(items[i]);
71
+ child.set$(item);
191
72
  } else {
192
- for (let k in items[i]) {
193
- child[k] = items[i][k];
194
- }
73
+ Object.assign(child, item);
195
74
  }
196
75
  }
197
76
  } else {
198
- if (!fragment) {
199
- fragment = document.createDocumentFragment();
200
- }
201
- let repeatItem = new itemClass();
77
+ child = new itemClass();
202
78
  if (isLazy) {
203
- repeatItem.lazyMode = true;
79
+ child.lazyMode = true;
80
+ }
81
+ Object.assign(child.init$ || child, item);
82
+ }
83
+ setItemWebMCPMetadata(child, item, index, keyProp ? item[keyProp] : undefined);
84
+ return child;
85
+ });
86
+ // Leaving elements are excluded from future reconciliation immediately.
87
+ for (let child of active) {
88
+ if (!retained.has(child)) {
89
+ child.setAttribute('inert', '');
90
+ animateOut(child);
91
+ }
92
+ }
93
+ let focused = el.ownerDocument.activeElement;
94
+ for (let index = 0; index < next.length; index++) {
95
+ let child = next[index];
96
+ let before = el.children[index] || null;
97
+ if (before !== child) {
98
+ let moveBefore = Reflect.get(el, 'moveBefore');
99
+ if (typeof moveBefore === 'function' && child.parentElement === el && el.isConnected) {
100
+ moveBefore.call(el, child, before);
101
+ } else {
102
+ el.insertBefore(child, before);
204
103
  }
205
- Object.assign((repeatItem?.init$ || repeatItem), items[i]);
206
- fragment.appendChild(repeatItem);
207
104
  }
208
105
  }
209
- fragment && el.appendChild(fragment);
210
- for (let i = prevLen - 1; i >= newLen; i--) {
211
- animateOut(children[i]);
106
+ if (focused instanceof HTMLElement && focused.isConnected
107
+ && el.contains(focused) && el.ownerDocument.activeElement !== focused) {
108
+ focused.focus({
109
+ preventScroll: true,
110
+ });
212
111
  }
213
-
214
- prevData = items;
215
- }, !clientSSR);
112
+ hydrating = false;
113
+ previous = items;
114
+ active = next;
115
+ });
216
116
  });
217
117
  }
@@ -1,17 +1,6 @@
1
1
  import { animateOut } from './animateOut.js';
2
2
  import { warnMsg } from './warn.js';
3
- import { setupItemize } from './itemizeSetup.js';
4
- import { DICT } from './dictionary.js';
5
-
6
- function setItemWebMCPMetadata(itemEl, item, idx) {
7
- if (!itemEl) return;
8
- itemEl[DICT.MCP_ITEM_INDEX_KEY] = idx;
9
- if (item && Object.prototype.hasOwnProperty.call(item, '_KEY_')) {
10
- itemEl[DICT.MCP_ITEM_KEY_KEY] = item._KEY_;
11
- } else {
12
- delete itemEl[DICT.MCP_ITEM_KEY_KEY];
13
- }
14
- }
3
+ import { setupItemize, setItemWebMCPMetadata } from './itemizeSetup.js';
15
4
 
16
5
  /**
17
6
  * @template {import('./Symbiote.js').Symbiote} T
@@ -1,6 +1,24 @@
1
1
  import { DICT } from './dictionary.js';
2
2
  import { ownElements } from './ownElements.js';
3
3
  import { initPropFallback } from './initPropFallback.js';
4
+ import { resolveTemplate } from './resolveTemplate.js';
5
+ import { warnMsg } from './warn.js';
6
+
7
+ /**
8
+ * @param {any} itemEl
9
+ * @param {any} item
10
+ * @param {number} idx
11
+ * @param {unknown} [key]
12
+ */
13
+ export function setItemWebMCPMetadata(itemEl, item, idx, key = item && Object.hasOwn(item, '_KEY_') ? item._KEY_ : undefined) {
14
+ if (!itemEl) { return; }
15
+ itemEl[DICT.MCP_ITEM_INDEX_KEY] = idx;
16
+ if (key !== undefined) {
17
+ itemEl[DICT.MCP_ITEM_KEY_KEY] = key;
18
+ } else {
19
+ delete itemEl[DICT.MCP_ITEM_KEY_KEY];
20
+ }
21
+ }
4
22
 
5
23
  /**
6
24
  * @typedef {Object} ItemizeDescriptor
@@ -29,6 +47,11 @@ export function setupItemize(fr, fnCtx, handler) {
29
47
  }).forEach((el) => {
30
48
  let itemTag = el.getAttribute(DICT.LIST_ITEM_TAG_ATTR);
31
49
  let repeatDataKey = el.getAttribute(DICT.LIST_ATTR);
50
+ let selector = el.getAttribute(DICT.USE_TPL_ATTR);
51
+ let selected = selector ? resolveTemplate(el, selector) : null;
52
+ if (selector && !selected) {
53
+ warnMsg(5, fnCtx.localName, selector);
54
+ }
32
55
  let itemClass;
33
56
  if (itemTag) {
34
57
  itemClass = window.customElements.get(itemTag);
@@ -53,8 +76,8 @@ export function setupItemize(fr, fnCtx, handler) {
53
76
  let staticEl = tpl.content.querySelector(
54
77
  `[${DICT.LIST_ATTR}="${repeatDataKey}"]`
55
78
  );
56
- itemClass.template = staticEl?.querySelector('template')?.innerHTML
57
- || el.children[0].innerHTML;
79
+ itemClass.template = selected?.innerHTML ?? (staticEl?.querySelector('template')?.innerHTML
80
+ || el.children[0].innerHTML);
58
81
  itemClass.reg(ssrTag);
59
82
  }
60
83
  } else {
@@ -66,7 +89,7 @@ export function setupItemize(fr, fnCtx, handler) {
66
89
  }
67
90
  }
68
91
  };
69
- itemClass.template = el.querySelector('template')?.innerHTML || el.innerHTML;
92
+ itemClass.template = selected?.innerHTML ?? (el.querySelector('template')?.innerHTML || el.innerHTML);
70
93
  itemClass.reg(itemTag);
71
94
  }
72
95
  }
@@ -9,9 +9,6 @@
9
9
  */
10
10
  export function ownElements(fr, selector) {
11
11
  let all = [...fr.querySelectorAll(selector)];
12
- if (!(fr instanceof HTMLElement) || !fr.localName?.includes('-')) {
13
- return all;
14
- }
15
12
  return all.filter((el) => {
16
13
  let parent = el.parentElement;
17
14
  while (parent && parent !== fr) {
@@ -25,7 +22,7 @@ export function ownElements(fr, selector) {
25
22
  /**
26
23
  * Check if a node belongs to `root` and not to a nested custom element.
27
24
  * @param {Node} node
28
- * @param {Element} root
25
+ * @param {Element | DocumentFragment} root
29
26
  * @returns {boolean}
30
27
  */
31
28
  export function isOwnNode(node, root) {
@@ -0,0 +1,12 @@
1
+ /**
2
+ * Native use-template lookup: the containing root takes precedence.
3
+ * @param {Element} element
4
+ * @param {string} selector
5
+ * @returns {HTMLTemplateElement | null}
6
+ */
7
+ export function resolveTemplate(element, selector) {
8
+ let root = /** @type {Document | ShadowRoot | DocumentFragment} */ (element.getRootNode());
9
+ return /** @type {HTMLTemplateElement | null} */ (
10
+ root.querySelector?.(selector) || element.ownerDocument.querySelector(selector)
11
+ );
12
+ }
@@ -194,11 +194,10 @@ function domBindProcessor(fr, fnCtx) {
194
194
  }
195
195
 
196
196
  function getTextNodesWithTokens(el) {
197
- let isCustomEl = el instanceof HTMLElement && el.localName?.includes('-');
198
197
  let node;
199
198
  let result = [];
200
199
  let acceptNode = (txt) => {
201
- if (isCustomEl && !isOwnNode(txt, el)) return NodeFilter.FILTER_REJECT;
200
+ if (!isOwnNode(txt, el)) return NodeFilter.FILTER_REJECT;
202
201
  return !txt.parentElement?.hasAttribute(DICT.TEXT_NODE_SKIP_ATTR)
203
202
  && txt.textContent.includes(DICT.TEXT_NODE_OPEN_TOKEN)
204
203
  && txt.textContent.includes(DICT.TEXT_NODE_CLOSE_TOKEN)
package/docs/README.md CHANGED
@@ -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
@@ -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 {
@@ -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
- For performance-critical lists, use the optional keyed itemize processor with reference-equality fast paths and key-based reconciliation:
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
- Up to **3× faster** for appends, **2×** for in-place updates, **32×** for no-ops.
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/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: `&`):