@verajs/renderer 0.2.0 → 0.2.2

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.
@@ -1,25 +1,82 @@
1
1
  /**
2
- * The profiler's in-page panel — live counts and the current churn list, in the corner of the app
3
- * you are already clicking through.
2
+ * The renderer's cross-file and public types — one `types.ts` at the import-graph root, per
3
+ * CODE-PRINCIPLES §1.
4
+ *
5
+ * **What is here and what deliberately is not.** Everything in this file is a pure data shape: it
6
+ * names no runtime value, so it can sit upstream of every module in the package and nothing here
7
+ * can pull a class into the import graph. The renderer's remaining cross-file types — `Item`,
8
+ * `ListStrategy`, `KeyedResult` — name the `Instance` and `ChildPart` CLASSES in their definitions,
9
+ * which puts them structurally downstream of `renderer.ts`; they stay beside those classes, and
10
+ * §1's "one file at the import-graph root" records that limit rather than pretending otherwise.
11
+ * Restating a class's shape here to satisfy the letter of the rule would create exactly the twin
12
+ * §1 forbids.
13
+ *
14
+ * Moving `ProfileReport` and `OverlayOptions` here dissolved a real cycle: `profiler.ts` imported
15
+ * `OverlayOptions` from `overlay.ts` while `overlay.ts` imported `ProfileReport` back from
16
+ * `profiler.ts`. Type-only, so it was erased and never a runtime cycle — but it is the shape this
17
+ * file's position in the graph exists to make impossible.
18
+ */
19
+ /**
20
+ * What a template tag (`html`, `svg`, `mathml`) produces — the compiled shape every renderer entry
21
+ * point accepts, and the one type a consumer normally names.
4
22
  *
5
- * Three constraints shaped this:
23
+ * `strings` is the template literal's own `strings` array and is the TEMPLATE'S IDENTITY: the
24
+ * engine interns it per call site, so two literals with identical text are two templates and
25
+ * rendering one after the other is a teardown, not an update. Anything building these by hand must
26
+ * hand back the same array to get an update.
27
+ */
28
+ type TemplateResult = {
29
+ /** 1 = html, 2 = svg, 3 = mathml — the markers core's built-in tags produce. */
30
+ _$litType$?: number;
31
+ strings: TemplateStringsArray;
32
+ values: unknown[];
33
+ /** Set by `keyed()`; drives keyed list reconciliation. */
34
+ key?: unknown;
35
+ };
36
+ /** One template identity replacing another at the same position, and how often. */
37
+ type Churn = {
38
+ /** The template that was torn down, rendered readably. */
39
+ from: string;
40
+ /** The template that replaced it. */
41
+ to: string;
42
+ /** How many times this exact swap happened while profiling. */
43
+ count: number;
44
+ /** Where in the DOM it happened, e.g. `main#app > ul.list`. First occurrence only. */
45
+ where: string;
46
+ };
47
+ /**
48
+ * What `getReport()`, `stopProfiling()` and `profile()` hand back.
6
49
  *
7
- * 1. **It must not render itself with the renderer.** Doing so would fold the overlay's own
8
- * commits into the numbers it reports. Everything here is plain DOM, updated in place.
9
- * 2. **It must not restyle the app.** It lives in a closed shadow root and sets every property it
10
- * depends on, so neither direction leaks.
11
- * 3. **It must work with no toolchain**, like everything else here — no CSS file, no framework,
12
- * one import.
50
+ * The number to read first is `rebuilds`, with `churn` naming the culprits: an update commits
51
+ * values into DOM that already exists, while a rebuild tears a subtree down and builds another,
52
+ * and a template that rebuilds every render is the single most expensive mistake available in this
53
+ * renderer. `creates` is not a problem — it is what rendering into an empty slot costs once.
13
54
  */
14
-
15
- interface OverlayOptions {
55
+ type ProfileReport = {
56
+ /** Completed top-level `render()` calls. Nested renders are folded into their outermost frame. */
57
+ frames: number;
58
+ /** Total milliseconds spent inside `render()`. */
59
+ ms: number;
60
+ /** The slowest single frame, in milliseconds. */
61
+ slowestFrameMs: number;
62
+ /** Templates committed in place — the good path. */
63
+ updates: number;
64
+ /** Templates rendered into a slot that held nothing. Unavoidable and not a problem. */
65
+ creates: number;
66
+ /** Templates that replaced a *different* template — a teardown, not an update. */
67
+ rebuilds: number;
68
+ /** Rebuilds grouped by template pair, worst first. */
69
+ churn: Churn[];
70
+ };
71
+ /** How `showProfiler()` places and paces its in-page panel. Every field has a default. */
72
+ type OverlayOptions = {
16
73
  /** Corner to pin to. Default `bottom-right`. */
17
74
  corner?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
18
75
  /** How often to repaint, in milliseconds. Default 400. */
19
76
  interval?: number;
20
77
  /** Churn rows to show before collapsing the rest into a count. Default 4. */
21
78
  rows?: number;
22
- }
79
+ };
23
80
 
24
81
  /**
25
82
  * @verajs/renderer — a ground-up, keyed, template-identity renderer.
@@ -80,14 +137,7 @@ interface OverlayOptions {
80
137
  * deliberately do not match the pattern: the first is an interop wire format, the second is called
81
138
  * by the DOM itself.
82
139
  */
83
- type TemplateResult = {
84
- /** 1 = html, 2 = svg, 3 = mathml — the markers core's built-in tags produce. */
85
- _$litType$?: number;
86
- strings: TemplateStringsArray;
87
- values: unknown[];
88
- /** Set by `keyed()`; drives keyed list reconciliation. */
89
- key?: unknown;
90
- };
140
+
91
141
  /**
92
142
  * Preserves the DOM of templates a child position toggles away from, instead of destroying it —
93
143
  * form values, scroll positions and media playback survive the round trip (lit-html calls this
@@ -145,33 +195,6 @@ declare const renderer: {
145
195
  }) => void;
146
196
  };
147
197
 
148
- /** One template identity replacing another at the same position, and how often. */
149
- interface Churn {
150
- /** The template that was torn down, rendered readably. */
151
- from: string;
152
- /** The template that replaced it. */
153
- to: string;
154
- /** How many times this exact swap happened while profiling. */
155
- count: number;
156
- /** Where in the DOM it happened, e.g. `main#app > ul.list`. First occurrence only. */
157
- where: string;
158
- }
159
- interface ProfileReport {
160
- /** Completed top-level `render()` calls. Nested renders are folded into their outermost frame. */
161
- frames: number;
162
- /** Total milliseconds spent inside `render()`. */
163
- ms: number;
164
- /** The slowest single frame, in milliseconds. */
165
- slowestFrameMs: number;
166
- /** Templates committed in place — the good path. */
167
- updates: number;
168
- /** Templates rendered into a slot that held nothing. Unavoidable and not a problem. */
169
- creates: number;
170
- /** Templates that replaced a *different* template — a teardown, not an update. */
171
- rebuilds: number;
172
- /** Rebuilds grouped by template pair, worst first. */
173
- churn: Churn[];
174
- }
175
198
  /** Begin collecting. Calling this while already profiling restarts the collection. */
176
199
  declare const startProfiling: () => void;
177
200
  /** What has been measured so far, without ending the session. Drives the live overlay. */
@@ -1 +1 @@
1
- {"version":3,"file":"vera-renderer-profiler.d.ts","sources":["../../src/overlay.ts","../../src/renderer.ts","../../src/profiler.ts"],"mappings":"AAwBA;;;;;;;;;;;;;;;;;;;;;;;ACxBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0DG;AAEH,KAAA,cAAS;AAYT;;;;;;;;;;;;;;;AAeG;AACH;AAEI;;AAGJ;;;AAGG;AACH,cAAA,IAAA;AACA,QAAM,cAAgB;AACtB;AAugBI;AACE;;AAEE;;AAEI;AACE;;;;;;;;;;;;AAYG;;AAEH;AACE,cAAA,UAAA,+BAAW,IAAA;;AACX;AAAG;;;AAGL;;;;AAIG;AACH;;AAEE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACxmBb,cAAA,SAAA,QAAA,aAAA;AACH;AASA,cAAS,aAAc,qBAAqB;AAK5C,yBAAyB;AAgCzB;AACA,iBAAe,OAAA,cAAA,OAAA,MAAA,OAAA;AACf;AACA,YAAW,aAAK;AAChB;AACA,iBAAgB,OAAA;AAChB;AACA,YAAY,aAAE;AACd;AACA;AAEA;AACA;AACA;AACA;;;AAEwB;AACtB;AACF;AAEA;AACA;AACA;;AAEE;AACE;AACA,cAAI,YAAc,aAAE,cAAA;;AACpB,cAAA,uBAA6B,aAAA;;;;","names":[]}
1
+ {"version":3,"file":"vera-renderer-profiler.d.ts","sources":["../../src/types.ts","../../src/renderer.ts","../../src/profiler.ts"],"mappings":"AAAA;;;;;;;;;;;;;;;;;AAiBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACjBH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0DG;;;;;;;;;;;;;;;;AAwBA;AACH;AAEI,kBAAgC;sBACvB;AAEb;;AA+cM;AAEN;AAEA;AAEA;AACE;;AAsBA;AACE;AACA;;;AAGA;AACA;AACA;AACE;;;AAEA;;AAGF;;;;;AAKG;AACH;;AAEA;AACA;;AAEE;AACE;AACA;;AAEJ;AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AC/jBD;AACH;AASA,cAAS,YAAc,2BAAqB;AAK5C;AAIA,cAAa,YAAM,WAAA,aAAA;;;;","names":[]}
@@ -763,6 +763,7 @@ const getTemplate = (result) => {
763
763
  templateCache.set(result.strings, (template = new Template(result)));
764
764
  return template;
765
765
  };
766
+ /** Anything bound to a live position: commits values[index..], returns the next value index. */
766
767
  const IGNORED_PART = { _commit: (_values, index) => index + 1 };
767
768
  /** Never equal to any user value, so the first commit always runs. */
768
769
  const UNSET = {};
@@ -800,6 +801,143 @@ const LIVE = 3;
800
801
  const EVENT = 4; // @name
801
802
  /** A binding that must never write — see the `__proto__` refusal in the constructor. */
802
803
  const REFUSED = -1;
804
+ /** `.name` on a custom element nothing receives yet — records into `_$props$`, then becomes
805
+ * `PROPERTY`. A distinct kind keeps the steady-state property path free of any adoption check. */
806
+ const PROP_ADOPT = 6;
807
+ /**
808
+ * The `PROP_ADOPT` commit, kept OUT of `_commit` so that function's size — and the JIT layout of
809
+ * its hot `PROPERTY`/`ATTR` branches — is unchanged from before this feature. `_commit` carries one
810
+ * dispatch line; all of this lives here, off every part's steady state.
811
+ *
812
+ * One question decides everything: **after the write, does anything receive this property?** An
813
+ * accessor anywhere on the chain — the platform's own (`title`, `hidden`), a component's declared
814
+ * one, or the pair core's `init()` defines — means the write just landed in real hands: no record,
815
+ * and the part rejoins `PROPERTY` for good. The walk is one step when the write created an own data
816
+ * property (nobody consumed it) and stops at the first descriptor either way, and it is what keeps
817
+ * a platform property on a lazy tag out of the record — recording `.title` would end with the drain
818
+ * shadowing `HTMLElement.prototype.title` and breaking it.
819
+ *
820
+ * An unreceived write is recorded under the sigiled expando **`_$props$`**, because two arrival
821
+ * orders both need it: on a LAZY tag the value sits as a plain own property that the class's field
822
+ * initializers will overwrite at upgrade (the clobber the `PROPERTY` branch only *detects*), and on
823
+ * an EAGER one the value survives but is indistinguishable from the component's own fields by the
824
+ * time `init()` runs. The record answers both — core's `init()` drains it, re-applying values
825
+ * unconditionally, which repairs BOTH spellings of the clobber (`item;` and `item = default`): it
826
+ * never asks whether a clobber happened, it asserts a bound value outranks a class default, which
827
+ * is what props mean. Element-carried because `./spread.ts` writes the same properties from a
828
+ * separate bundle with no shared registry — the `_$`-sigiled member is the cross-bundle channel,
829
+ * and the recorder there is this one's deliberate twin.
830
+ *
831
+ * Returns the part's NEXT kind: `PROPERTY` once something receives the property or the element is
832
+ * upgraded (its record is final — `init()` drains it in the same tick) or has no realm; `REFUSED`
833
+ * for a getter with no setter, so the binding goes inert instead of the flipped plain write
834
+ * throwing on the next commit; `0` to stay adopting — a dash-named element that never upgrades and
835
+ * never receives keeps recording, so its record stays current rather than staling. The one
836
+ * retention this leaves: a defined non-vera element with a plain data property keeps its FIRST
837
+ * committed values in `_$props$` for its lifetime — bounded, one generation, and the part itself
838
+ * already retains the current generation in `_committed`.
839
+ */
840
+ const commitAdopt = (element, name, value) => {
841
+ const el = element;
842
+ /**
843
+ * The walk comes BEFORE the write, because what the walk finds decides whether writing is even
844
+ * legal: a SETTER receives the value (and a setter that throws is the component's own error), a
845
+ * GETTER with no setter cannot — the old order assigned first, which in strict mode threw a raw
846
+ * TypeError out of the render for the eager spelling of exactly the case the drain refuses by
847
+ * name for the lazy one. Same contested state, one rule, both arrival orders — and the server's
848
+ * `deliverProperty` applies it too. The dev warning defers to `_$adopt$` where it exists: an
849
+ * initialized component's drain already speaks, and two voices for one binding is noise.
850
+ */
851
+ let carrier = el;
852
+ while (carrier !== null) {
853
+ const desc = Object.getOwnPropertyDescriptor(carrier, name);
854
+ if (desc !== undefined) {
855
+ if (desc.set !== undefined) {
856
+ el[name] = value;
857
+ return PROPERTY;
858
+ }
859
+ if (desc.get !== undefined) {
860
+ /** An initialized component's receiver owns the refusal (and its channel); for anything
861
+ * else this is the only door, so it says so itself. Either way the binding goes INERT —
862
+ * flipping to `PROPERTY` would make the next commit's plain write throw. */
863
+ if (el._$adopt$ !== undefined)
864
+ el._$adopt$(name, value);
865
+ else if (true )
866
+ console.warn(`[vera] renderer: <${element.localName}> declares \`${name}\` as a getter with no ` +
867
+ `setter — the value bound by \`.${name}=\${…}\` cannot be delivered and the binding ` +
868
+ `is ignored. Add a setter, or stop binding it.`);
869
+ return REFUSED;
870
+ }
871
+ break; // a data property — an own field, or an inherited default: nothing receives it
872
+ }
873
+ carrier = Object.getPrototypeOf(carrier);
874
+ }
875
+ el[name] = value;
876
+ /**
877
+ * An initialized component receives LIVE: `init()` left `_$adopt$` on the element, and a key it
878
+ * has not adopted yet goes through that door — a record here would never be read again, because
879
+ * the drain already ran. This is how a hydrated child gets the props its parent commits after
880
+ * the child settled, and how a spread bag's conditional key arrives reactive on a live element.
881
+ */
882
+ if (el._$adopt$ !== undefined) {
883
+ el._$adopt$(name, value);
884
+ return PROPERTY;
885
+ }
886
+ const record = (el._$props$ ??= {});
887
+ const firstRecording = !Object.hasOwn(record, name);
888
+ record[name] = value;
889
+ /**
890
+ * Upgrade is read off the PROTOTYPE, never off `el.constructor`: a spread bag's keys are runtime
891
+ * data, so a bag carrying a key named `constructor` writes an own property that shadows the real
892
+ * one, and a check that reads it would then misjudge every later commit. No property write can
893
+ * move an element's prototype — the one assignment that could, `__proto__`, both twins refuse.
894
+ * The realm comes from the element, as always.
895
+ */
896
+ const win = element.ownerDocument.defaultView;
897
+ const upgraded = win === null || Object.getPrototypeOf(el) !== win.HTMLElement.prototype;
898
+ /**
899
+ * **The clobber detector, for the element the drain will never reach.** A component that calls
900
+ * `init()` has the record re-applied, so for it the pre-upgrade window is repaired; an element
901
+ * that never drains — a plain custom element with a class field — still loses the bound value to
902
+ * the field initializer at upgrade, exactly as before this feature, and still deserves the
903
+ * warning. Told apart by OWNERSHIP, not by value: after the definition arrives (and, for a
904
+ * connected element, `connectedCallback` and the drain have run synchronously inside `define()`),
905
+ * an own accessor means the drain took the property and there is nothing to report. Identity
906
+ * against the COMMITTED value would lie twice — a drained value reads back through the store's
907
+ * proxy, and a value superseded by a later pre-upgrade commit differs without anything being
908
+ * wrong — so the comparison is against the RECORD, which later recordings keep current, and the
909
+ * subscription is installed once per (element, property), on the first recording. The registry
910
+ * is the element's own realm's. Development only; production carries no check, no message, no
911
+ * `whenDefined` subscription.
912
+ */
913
+ if (true && win !== null && !upgraded && firstRecording) {
914
+ const tag = element.localName;
915
+ win.customElements.whenDefined(tag).then(() => {
916
+ /** Ownership is asked of the whole CHAIN: the drain's own accessor, a class's prototype
917
+ * pair the value was handed to, or a get-only surface the drain refused by name — every
918
+ * one means the property has an owner and this closure has nothing left to report. */
919
+ let carrier = el;
920
+ let owned = false;
921
+ while (carrier !== null) {
922
+ const desc = Object.getOwnPropertyDescriptor(carrier, name);
923
+ if (desc !== undefined) {
924
+ owned = desc.get !== undefined || desc.set !== undefined;
925
+ break;
926
+ }
927
+ carrier = Object.getPrototypeOf(carrier);
928
+ }
929
+ if (!owned && el[name] !== record[name])
930
+ console.warn(`[vera] renderer: the value bound by \`.${name}=\${…}\` on <${tag}> was replaced ` +
931
+ `while the element upgraded. A class field is the usual cause: at ES2022 ` +
932
+ `\`${name}?: …\` emits \`${name};\`, which runs during upgrade and overwrites ` +
933
+ `whatever was set beforehand — write it \`declare ${name}?: …\` instead, which ` +
934
+ `emits nothing. A component that calls init() adopts bound properties automatically ` +
935
+ `and never sees this; this element did not. Ignore this if the component replaced ` +
936
+ `the value on purpose.`);
937
+ });
938
+ }
939
+ return upgraded ? PROPERTY : 0;
940
+ };
803
941
  /**
804
942
  * Calls an element ref, and survives one that throws.
805
943
  *
@@ -890,6 +1028,19 @@ class AttrPart {
890
1028
  kind = EVENT;
891
1029
  realName = name.slice(2).toLowerCase();
892
1030
  }
1031
+ /**
1032
+ * **A property write to a custom element starts as `PROP_ADOPT`**, a distinct kind so the
1033
+ * steady-state `PROPERTY` commit path stays byte-for-byte unchanged — zero added instruction
1034
+ * for every `.value=` on a built-in. Every dash-named element starts here, defined or not,
1035
+ * because the record has to exist for BOTH arrival orders: an eager component's first commit
1036
+ * lands after upgrade but before `init()` (one commit records, then the part flips), and a
1037
+ * lazy one's land before upgrade (the part records until the definition arrives). `commitAdopt`
1038
+ * decides which per commit and flips the part back to `PROPERTY` the moment something real
1039
+ * receives the property, so the window is one commit for a defined element and the pre-upgrade
1040
+ * stretch for a lazy one.
1041
+ */
1042
+ if (kind === PROPERTY && element.localName.includes('-'))
1043
+ kind = PROP_ADOPT;
893
1044
  this._kind = kind;
894
1045
  this._name = realName;
895
1046
  this._element = element;
@@ -1002,13 +1153,29 @@ class AttrPart {
1002
1153
  if (kind === LIVE) {
1003
1154
  this._committed = value;
1004
1155
  /**
1005
- * **Except while adopting.** Hydration reaches a DOM a person may already have used, and the
1006
- * click that checked a radio happened before any handler existed to tell the store about it —
1007
- * so re-asserting the server's choice here would throw the interaction away and nothing would
1008
- * ever put it back. Recorded, not written, exactly as the other form properties are; the
1009
- * first state-driven render after that applies live semantics normally.
1156
+ * **Except while adopting — on a form control.** Hydration reaches a DOM a person may
1157
+ * already have used, and the click that checked a radio happened before any handler existed
1158
+ * to tell the store about it — so re-asserting the server's choice here would throw the
1159
+ * interaction away and nothing would ever put it back. Recorded, not written, exactly as
1160
+ * the other form properties are; the first state-driven render after that applies live
1161
+ * semantics normally.
1162
+ *
1163
+ * **A COMPONENT tag is the exception to the exception**: there is no user-editable carrier
1164
+ * behind `!prop` on a component — it is a property delivery spelled with `!` — and the
1165
+ * server DELIVERED it to the child's render, so yielding here dropped the one copy the
1166
+ * client would ever get and hydration regressed the child's content to its prop-less state.
1167
+ * Found by the hydration fixture on its first run. The write is unconditional and routes
1168
+ * through the element like any component prop: an accessor receives it, an initialized
1169
+ * component adopts it live.
1010
1170
  */
1011
- if (!(false && adopting)) {
1171
+ if (false && adopting) {
1172
+ /** Routed through `commitAdopt`, not written raw: the child hydrated BEFORE this commit,
1173
+ * so only the adoption door re-runs its render. The part stays `LIVE` — the return is
1174
+ * deliberately dropped — so live semantics resume on the next state-driven render. */
1175
+ if (this._element.localName.includes('-'))
1176
+ commitAdopt(this._element, this._name, value);
1177
+ }
1178
+ else {
1012
1179
  const liveTarget = this._element;
1013
1180
  if (liveTarget[this._name] !== value)
1014
1181
  liveTarget[this._name] = value;
@@ -1088,52 +1255,16 @@ class AttrPart {
1088
1255
  this._committed = value;
1089
1256
  return index + this._slots;
1090
1257
  }
1091
- target[name] = value;
1092
1258
  /**
1093
- * Detection only, and deliberately not repair.
1094
- *
1095
- * A property set on a custom element that has not upgraded yet lands as an own property on
1096
- * the instance. When the definition arrives — lazily imported, code-split, or a module that
1097
- * simply had not run — `customElements.define` upgrades synchronously and the class's field
1098
- * initializers execute. At target ES2022 a field declaration is a `[[Define]]`, so
1099
- * `item?: T` emits `item;` and overwrites the bound value with `undefined`. Nothing throws;
1100
- * it reads as broken reactivity.
1101
- *
1102
- * Repairing it was tried and removed. Re-applying when the slot came back `undefined`
1103
- * covered `item?: T` but not `item = someDefault`, which overwrites with the default and
1104
- * never looks clobbered — so the repair was silently partial, and made the bug intermittent
1105
- * across two spellings of the same mistake. It also cost 74 B in every app while leaving
1106
- * `declare` mandatory anyway, because a property assigned imperatively is unrecoverable:
1107
- * the renderer never saw it, and by the time `init()` runs the value is already gone.
1108
- *
1109
- * So this is `true `-only and production pays nothing — no check, no message, no
1110
- * `whenDefined` subscription. Lit reached the same place from the other direction and
1111
- * throws (`lit.dev/msg/class-field-shadowing`); a warning suffices here because Vera has no
1112
- * prototype accessors to shadow permanently — the damage is one lost value, not a property
1113
- * that never updates again.
1259
+ * No un-upgraded custom element can be behind this write: a dash-named property part is
1260
+ * born `PROP_ADOPT` and only flips here once something receives the property, so the
1261
+ * pre-upgrade window — the clobber, its repair for components, and the `whenDefined`
1262
+ * detector for elements that never drain — lives entirely in `commitAdopt` above. History
1263
+ * worth keeping: an earlier repair was tried HERE and removed as silently partial (it
1264
+ * re-applied on `undefined`, so `item = someDefault` never looked clobbered); the record
1265
+ * the drain re-applies unconditionally is what answered that objection.
1114
1266
  */
1115
- if (true ) {
1116
- const tag = this._element.localName;
1117
- if (tag.indexOf('-') > 0 && !customElements.get(tag)) {
1118
- customElements.whenDefined(tag).then(() => {
1119
- /**
1120
- * States what was observed rather than diagnosing it. A class field is the usual
1121
- * cause by a wide margin, but a component that assigns the property itself during
1122
- * upgrade produces the same observation, and that is a legitimate — if confusing —
1123
- * thing to do, since the renderer's dirty check will not re-apply the bound value on
1124
- * the next render either.
1125
- */
1126
- if (target[name] !== value)
1127
- console.warn(`[vera] renderer: the value bound by \`.${name}=\${…}\` on <${tag}> was replaced ` +
1128
- `while the element upgraded. A class field is the usual cause: at ES2022 ` +
1129
- `\`${name}?: …\` emits \`${name};\`, which runs during upgrade and overwrites ` +
1130
- `whatever was set beforehand — write it \`declare ${name}?: …\` instead, which ` +
1131
- `emits nothing. A plain field also wipes properties assigned imperatively, ` +
1132
- `which cannot be detected at all. Ignore this if the component replaced the ` +
1133
- `value on purpose.`);
1134
- });
1135
- }
1136
- }
1267
+ target[name] = value;
1137
1268
  }
1138
1269
  else if (kind === BOOLEAN) {
1139
1270
  /** Unconditional for the same reason: `<b hidden ?hidden=${false}>` must end up not hidden. */
@@ -1160,6 +1291,11 @@ class AttrPart {
1160
1291
  this._element.addEventListener(this._name, this);
1161
1292
  this._handler = value ?? null;
1162
1293
  }
1294
+ else if (kind === PROP_ADOPT) {
1295
+ const next = commitAdopt(this._element, this._name, value);
1296
+ if (next !== 0)
1297
+ this._kind = next;
1298
+ }
1163
1299
  else if (value != null) {
1164
1300
  /**
1165
1301
  * Element ref: `<input ${myRef} />`. A function is called with the element; an object gets
@@ -1422,6 +1558,38 @@ const isTemplateResult = (value) => value.strings !== undefined;
1422
1558
  * with a text node — so the steady state is compare-and-assign on `.data`. This part carries only
1423
1559
  * that, upgrading itself to a full ChildPart the first time it sees null, a template, or an array.
1424
1560
  */
1561
+ /**
1562
+ * **A boolean in a child position renders the WORD, and almost nobody means that.**
1563
+ *
1564
+ * `${items.length > 0 && html`…`}` is the ordinary conditional idiom, and when the test is false
1565
+ * the whole expression is `false` — which becomes the text `false` on the page. Nothing throws;
1566
+ * the value is legitimate; only the intent is wrong. lit-html does the same and this renderer
1567
+ * matches it deliberately (anything not nullish renders), so the BEHAVIOUR stays and the mistake
1568
+ * is named where it happens instead of being found by looking at the page.
1569
+ *
1570
+ * `@verajs/jsx` compiles this case away — in JSX a boolean child becomes nothing, React's rule,
1571
+ * because that is where React expectations live. **That is the one value semantic on which JSX and
1572
+ * a hand-written template differ**, which makes this the warning that meets JSX-shaped code pasted
1573
+ * into a template.
1574
+ *
1575
+ * Called from BOTH child sinks, because a text position is a `TextPart` until something upgrades
1576
+ * it and a boolean never triggers that upgrade — putting the check in `ChildPart` alone left it
1577
+ * silent for exactly the common case. One function, two call sites, per the standing rule that a
1578
+ * deliberate duplication is a fix's second address.
1579
+ *
1580
+ * Both sinks gate this on the value CHANGING — not merely on reaching a commit — so an unchanged
1581
+ * `false` is reported once and not once per render. `ChildPart` needed that stated explicitly: its
1582
+ * dirty check sits below, and calling this above it spammed every pass.
1583
+ */
1584
+ const warnBooleanChild = (value) => {
1585
+ if (typeof value !== 'boolean')
1586
+ return;
1587
+ console.warn(`[vera] renderer: a child position was given \`${value}\`, which renders as the word ` +
1588
+ `"${value}" — the usual cause is \`\${cond && …}\` with a false \`cond\`.\n` +
1589
+ `Write \`\${cond ? … : null}\`, or \`\${(cond && …) || null}\`; \`null\` and \`undefined\` are ` +
1590
+ `the values that render nothing. If you meant to display the boolean, say so with ` +
1591
+ `\`\${String(value)}\` and this goes quiet.`);
1592
+ };
1425
1593
  class TextPart {
1426
1594
  _text;
1427
1595
  _value = '';
@@ -1477,6 +1645,8 @@ class TextPart {
1477
1645
  return index + 1;
1478
1646
  }
1479
1647
  if (value !== this._value) {
1648
+ if (true )
1649
+ warnBooleanChild(value);
1480
1650
  this._value = value;
1481
1651
  this._text.data = value;
1482
1652
  }
@@ -1766,6 +1936,15 @@ class ChildPart {
1766
1936
  return;
1767
1937
  }
1768
1938
  if (typeof value !== 'object') {
1939
+ /**
1940
+ * Gated on the value CHANGING, which is the same condition the commit below uses. Called
1941
+ * before that check it fired on every render of an unchanged `false` — a channel that
1942
+ * repeats is as useless as one that stays silent, and the comment on `warnBooleanChild`
1943
+ * claimed this was already true. `_value` holds whatever was last committed here, so a part
1944
+ * arriving from a template state differs and reports once.
1945
+ */
1946
+ if (true && this._value !== value)
1947
+ warnBooleanChild(value);
1769
1948
  if (this._mode === TEXT) {
1770
1949
  if (this._value !== value) {
1771
1950
  this._value = value;