@openelement/element 0.41.0-alpha.1

package/src/open-element-render.js

@@ -0,0 +1,91 @@
+/**
+ * Internal rendering helpers for OpenElement.
+ *
+ * Extracted from open-element.ts to keep the base class focused on its
+ * public lifecycle API. These functions are NOT part of the public package
+ * surface and should only be consumed by OpenElement itself.
+ *
+ * @internal
+ * @module @openelement/element/open-element-render
+ */ import { renderToDom } from '@openelement/core';
+import { formatError } from '@openelement/core/errors';
+import { createLogger } from '@openelement/core/logger';
+/**
+ * Dispose all reactive effects and declarative event listeners created by
+ * previous renders or hydration passes.
+ *
+ * Returns a fresh, empty event-cleanup array so callers can replace their
+ * existing bag and avoid retaining stale closures.
+ */ export function disposeRenderBindings(effectDisposers, eventCleanups) {
+  for (const d of effectDisposers)d();
+  effectDisposers.clear();
+  for (const f of eventCleanups)f();
+  return [];
+}
+/**
+ * CSR render path for light-DOM components.
+ *
+ * Clears previous bindings, calls render(), caches the result, and mounts the
+ * produced DOM into the element itself.
+ */ export function renderIntoLightDom(instance, effectDisposers, eventCleanups, cache) {
+  const newEventCleanups = disposeRenderBindings(effectDisposers, eventCleanups);
+  const result = instance.render();
+  cache.set(result);
+  const self = instance;
+  while(self.firstChild){
+    self.removeChild(self.firstChild);
+  }
+  if (result != null) {
+    self.appendChild(renderToDom(result, undefined, effectDisposers, instance.signalRegistry));
+  }
+  return newEventCleanups;
+}
+/**
+ * CSR render path for shadow-DOM components.
+ *
+ * Clears previous bindings, calls render(), caches the result, and mounts the
+ * produced DOM into the shadow root.
+ */ export function renderIntoShadowRoot(instance, effectDisposers, eventCleanups, cache) {
+  const root = instance.shadowRoot;
+  if (!root) return eventCleanups;
+  const newEventCleanups = disposeRenderBindings(effectDisposers, eventCleanups);
+  const result = instance.render();
+  cache.set(result);
+  if (result != null) {
+    while(root.firstChild){
+      root.removeChild(root.firstChild);
+    }
+    root.appendChild(renderToDom(result, undefined, effectDisposers, instance.signalRegistry));
+  }
+  return newEventCleanups;
+}
+/**
+ * Render a fallback VNode when the unified render/hydrate path throws.
+ *
+ * Ensures the render root exists, invokes onRenderError(), disposes any
+ * previous bindings, and mounts the fallback content.
+ */ export function renderErrorFallback(instance, error, effectDisposers, eventCleanups, onRenderError) {
+  const ctor = instance.constructor;
+  const isLightDom = ctor.renderMode === 'light';
+  if (!instance.shadowRoot && !isLightDom) {
+    instance.createRenderRoot();
+  }
+  const target = isLightDom ? instance : instance.shadowRoot;
+  if (!target) return [];
+  let fallback;
+  try {
+    fallback = onRenderError(error);
+  } catch (fallbackError) {
+    createLogger('dsd').error(`<${instance.tagName.toLowerCase()}> onRenderError failed: ${formatError(fallbackError)}`);
+    fallback = null;
+  }
+  const newEventCleanups = disposeRenderBindings(effectDisposers, eventCleanups);
+  if (fallback != null) {
+    while(target.firstChild){
+      target.removeChild(target.firstChild);
+    }
+    target.appendChild(renderToDom(fallback, undefined, effectDisposers, instance.signalRegistry));
+  }
+  return newEventCleanups;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbImZpbGU6Ly8vaG9tZS9ydW5uZXIvd29yay9vcGVuZWxlbWVudC9vcGVuZWxlbWVudC9wYWNrYWdlcy9lbGVtZW50L3NyYy9vcGVuLWVsZW1lbnQtcmVuZGVyLnRzIl0sInNvdXJjZXNDb250ZW50IjpbIi8qKlxuICogSW50ZXJuYWwgcmVuZGVyaW5nIGhlbHBlcnMgZm9yIE9wZW5FbGVtZW50LlxuICpcbiAqIEV4dHJhY3RlZCBmcm9tIG9wZW4tZWxlbWVudC50cyB0byBrZWVwIHRoZSBiYXNlIGNsYXNzIGZvY3VzZWQgb24gaXRzXG4gKiBwdWJsaWMgbGlmZWN5Y2xlIEFQSS4gVGhlc2UgZnVuY3Rpb25zIGFyZSBOT1QgcGFydCBvZiB0aGUgcHVibGljIHBhY2thZ2VcbiAqIHN1cmZhY2UgYW5kIHNob3VsZCBvbmx5IGJlIGNvbnN1bWVkIGJ5IE9wZW5FbGVtZW50IGl0c2VsZi5cbiAqXG4gKiBAaW50ZXJuYWxcbiAqIEBtb2R1bGUgQG9wZW5lbGVtZW50L2VsZW1lbnQvb3Blbi1lbGVtZW50LXJlbmRlclxuICovXG5cbmltcG9ydCB0eXBlIHsgVk5vZGUgfSBmcm9tICdAb3BlbmVsZW1lbnQvcHJvdG9jb2wvdm5vZGUnO1xuaW1wb3J0IHsgcmVuZGVyVG9Eb20gfSBmcm9tICdAb3BlbmVsZW1lbnQvY29yZSc7XG5pbXBvcnQgeyBmb3JtYXRFcnJvciB9IGZyb20gJ0BvcGVuZWxlbWVudC9jb3JlL2Vycm9ycyc7XG5pbXBvcnQgeyBjcmVhdGVMb2dnZXIgfSBmcm9tICdAb3BlbmVsZW1lbnQvY29yZS9sb2dnZXInO1xuaW1wb3J0IHR5cGUgeyBPcGVuRWxlbWVudCB9IGZyb20gJy4vb3Blbi1lbGVtZW50LmpzJztcblxuLyoqXG4gKiBNaW5pbWFsIGFjY2Vzc29yIGZvciB0aGUgVk5vZGUgY2FjaGUgc3RvcmVkIG9uIGFuIE9wZW5FbGVtZW50IGluc3RhbmNlLlxuICpcbiAqIFRoZSBjYWNoZSBsaXZlcyBhcyB0cnVlIHByaXZhdGUgZmllbGRzIG9uIHRoZSBjbGFzcywgc28gaGVscGVycyBpbnRlcmFjdFxuICogd2l0aCBpdCB0aHJvdWdoIHRoaXMgc21hbGwgZmFjYWRlIGluc3RlYWQgb2YgdHJ5aW5nIHRvIGFjY2VzcyAjcHJpdmF0ZVxuICogc3RhdGUgZnJvbSBvdXRzaWRlIHRoZSBjbGFzcyBib2R5LlxuICovXG5leHBvcnQgaW50ZXJmYWNlIFZOb2RlQ2FjaGVBY2Nlc3Mge1xuICAvKiogUmVhZCB0aGUgY3VycmVudCBjYWNoZWQgVk5vZGUgYW5kIHdoZXRoZXIgaXQgaXMgdmFsaWQuICovXG4gIGdldCgpOiB7IHZub2RlOiB1bmtub3duOyB2YWxpZDogYm9vbGVhbiB9O1xuICAvKiogU3RvcmUgYSBWTm9kZSBhbmQgbWFyayB0aGUgY2FjaGUgdmFsaWQuICovXG4gIHNldCh2bm9kZTogdW5rbm93bik6IHZvaWQ7XG59XG5cbi8qKlxuICogRGlzcG9zZSBhbGwgcmVhY3RpdmUgZWZmZWN0cyBhbmQgZGVjbGFyYXRpdmUgZXZlbnQgbGlzdGVuZXJzIGNyZWF0ZWQgYnlcbiAqIHByZXZpb3VzIHJlbmRlcnMgb3IgaHlkcmF0aW9uIHBhc3Nlcy5cbiAqXG4gKiBSZXR1cm5zIGEgZnJlc2gsIGVtcHR5IGV2ZW50LWNsZWFudXAgYXJyYXkgc28gY2FsbGVycyBjYW4gcmVwbGFjZSB0aGVpclxuICogZXhpc3RpbmcgYmFnIGFuZCBhdm9pZCByZXRhaW5pbmcgc3RhbGUgY2xvc3VyZXMuXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiBkaXNwb3NlUmVuZGVyQmluZGluZ3MoXG4gIGVmZmVjdERpc3Bvc2VyczogU2V0PCgpID0+IHZvaWQ+LFxuICBldmVudENsZWFudXBzOiBBcnJheTwoKSA9PiB2b2lkPixcbik6IEFycmF5PCgpID0+IHZvaWQ+IHtcbiAgZm9yIChjb25zdCBkIG9mIGVmZmVjdERpc3Bvc2VycykgZCgpO1xuICBlZmZlY3REaXNwb3NlcnMuY2xlYXIoKTtcbiAgZm9yIChjb25zdCBmIG9mIGV2ZW50Q2xlYW51cHMpIGYoKTtcbiAgcmV0dXJuIFtdO1xufVxuXG4vKipcbiAqIENTUiByZW5kZXIgcGF0aCBmb3IgbGlnaHQtRE9NIGNvbXBvbmVudHMuXG4gKlxuICogQ2xlYXJzIHByZXZpb3VzIGJpbmRpbmdzLCBjYWxscyByZW5kZXIoKSwgY2FjaGVzIHRoZSByZXN1bHQsIGFuZCBtb3VudHMgdGhlXG4gKiBwcm9kdWNlZCBET00gaW50byB0aGUgZWxlbWVudCBpdHNlbGYuXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiByZW5kZXJJbnRvTGlnaHREb20oXG4gIGluc3RhbmNlOiBPcGVuRWxlbWVudCxcbiAgZWZmZWN0RGlzcG9zZXJzOiBTZXQ8KCkgPT4gdm9pZD4sXG4gIGV2ZW50Q2xlYW51cHM6IEFycmF5PCgpID0+IHZvaWQ+LFxuICBjYWNoZTogVk5vZGVDYWNoZUFjY2Vzcyxcbik6IEFycmF5PCgpID0+IHZvaWQ+IHtcbiAgY29uc3QgbmV3RXZlbnRDbGVhbnVwcyA9IGRpc3Bvc2VSZW5kZXJCaW5kaW5ncyhlZmZlY3REaXNwb3NlcnMsIGV2ZW50Q2xlYW51cHMpO1xuXG4gIGNvbnN0IHJlc3VsdCA9IGluc3RhbmNlLnJlbmRlcigpO1xuICBjYWNoZS5zZXQocmVzdWx0KTtcblxuICBjb25zdCBzZWxmID0gaW5zdGFuY2UgYXMgSFRNTEVsZW1lbnQ7XG4gIHdoaWxlIChzZWxmLmZpcnN0Q2hpbGQpIHtcbiAgICBzZWxmLnJlbW92ZUNoaWxkKHNlbGYuZmlyc3RDaGlsZCk7XG4gIH1cblxuICBpZiAocmVzdWx0ICE9IG51bGwpIHtcbiAgICBzZWxmLmFwcGVuZENoaWxkKHJlbmRlclRvRG9tKHJlc3VsdCwgdW5kZWZpbmVkLCBlZmZlY3REaXNwb3NlcnMsIGluc3RhbmNlLnNpZ25hbFJlZ2lzdHJ5KSk7XG4gIH1cblxuICByZXR1cm4gbmV3RXZlbnRDbGVhbnVwcztcbn1cblxuLyoqXG4gKiBDU1IgcmVuZGVyIHBhdGggZm9yIHNoYWRvdy1ET00gY29tcG9uZW50cy5cbiAqXG4gKiBDbGVhcnMgcHJldmlvdXMgYmluZGluZ3MsIGNhbGxzIHJlbmRlcigpLCBjYWNoZXMgdGhlIHJlc3VsdCwgYW5kIG1vdW50cyB0aGVcbiAqIHByb2R1Y2VkIERPTSBpbnRvIHRoZSBzaGFkb3cgcm9vdC5cbiAqL1xuZXhwb3J0IGZ1bmN0aW9uIHJlbmRlckludG9TaGFkb3dSb290KFxuICBpbnN0YW5jZTogT3BlbkVsZW1lbnQsXG4gIGVmZmVjdERpc3Bvc2VyczogU2V0PCgpID0+IHZvaWQ+LFxuICBldmVudENsZWFudXBzOiBBcnJheTwoKSA9PiB2b2lkPixcbiAgY2FjaGU6IFZOb2RlQ2FjaGVBY2Nlc3MsXG4pOiBBcnJheTwoKSA9PiB2b2lkPiB7XG4gIGNvbnN0IHJvb3QgPSBpbnN0YW5jZS5zaGFkb3dSb290O1xuICBpZiAoIXJvb3QpIHJldHVybiBldmVudENsZWFudXBzO1xuXG4gIGNvbnN0IG5ld0V2ZW50Q2xlYW51cHMgPSBkaXNwb3NlUmVuZGVyQmluZGluZ3MoZWZmZWN0RGlzcG9zZXJzLCBldmVudENsZWFudXBzKTtcblxuICBjb25zdCByZXN1bHQgPSBpbnN0YW5jZS5yZW5kZXIoKTtcbiAgY2FjaGUuc2V0KHJlc3VsdCk7XG5cbiAgaWYgKHJlc3VsdCAhPSBudWxsKSB7XG4gICAgd2hpbGUgKHJvb3QuZmlyc3RDaGlsZCkge1xuICAgICAgcm9vdC5yZW1vdmVDaGlsZChyb290LmZpcnN0Q2hpbGQpO1xuICAgIH1cbiAgICByb290LmFwcGVuZENoaWxkKHJlbmRlclRvRG9tKHJlc3VsdCwgdW5kZWZpbmVkLCBlZmZlY3REaXNwb3NlcnMsIGluc3RhbmNlLnNpZ25hbFJlZ2lzdHJ5KSk7XG4gIH1cblxuICByZXR1cm4gbmV3RXZlbnRDbGVhbnVwcztcbn1cblxuLyoqXG4gKiBSZW5kZXIgYSBmYWxsYmFjayBWTm9kZSB3aGVuIHRoZSB1bmlmaWVkIHJlbmRlci9oeWRyYXRlIHBhdGggdGhyb3dzLlxuICpcbiAqIEVuc3VyZXMgdGhlIHJlbmRlciByb290IGV4aXN0cywgaW52b2tlcyBvblJlbmRlckVycm9yKCksIGRpc3Bvc2VzIGFueVxuICogcHJldmlvdXMgYmluZGluZ3MsIGFuZCBtb3VudHMgdGhlIGZhbGxiYWNrIGNvbnRlbnQuXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiByZW5kZXJFcnJvckZhbGxiYWNrKFxuICBpbnN0YW5jZTogT3BlbkVsZW1lbnQsXG4gIGVycm9yOiB1bmtub3duLFxuICBlZmZlY3REaXNwb3NlcnM6IFNldDwoKSA9PiB2b2lkPixcbiAgZXZlbnRDbGVhbnVwczogQXJyYXk8KCkgPT4gdm9pZD4sXG4gIG9uUmVuZGVyRXJyb3I6IChlcnJvcjogdW5rbm93bikgPT4gVk5vZGUgfCBudWxsLFxuKTogQXJyYXk8KCkgPT4gdm9pZD4ge1xuICBjb25zdCBjdG9yID0gaW5zdGFuY2UuY29uc3RydWN0b3IgYXMgdHlwZW9mIE9wZW5FbGVtZW50O1xuICBjb25zdCBpc0xpZ2h0RG9tID0gY3Rvci5yZW5kZXJNb2RlID09PSAnbGlnaHQnO1xuXG4gIGlmICghaW5zdGFuY2Uuc2hhZG93Um9vdCAmJiAhaXNMaWdodERvbSkge1xuICAgIGluc3RhbmNlLmNyZWF0ZVJlbmRlclJvb3QoKTtcbiAgfVxuXG4gIGNvbnN0IHRhcmdldCA9IGlzTGlnaHREb20gPyAoaW5zdGFuY2UgYXMgSFRNTEVsZW1lbnQpIDogaW5zdGFuY2Uuc2hhZG93Um9vdDtcbiAgaWYgKCF0YXJnZXQpIHJldHVybiBbXTtcblxuICBsZXQgZmFsbGJhY2s6IFZOb2RlIHwgbnVsbDtcbiAgdHJ5IHtcbiAgICBmYWxsYmFjayA9IG9uUmVuZGVyRXJyb3IoZXJyb3IpO1xuICB9IGNhdGNoIChmYWxsYmFja0Vycm9yKSB7XG4gICAgY3JlYXRlTG9nZ2VyKCdkc2QnKS5lcnJvcihcbiAgICAgIGA8JHtpbnN0YW5jZS50YWdOYW1lLnRvTG93ZXJDYXNlKCl9PiBvblJlbmRlckVycm9yIGZhaWxlZDogJHtmb3JtYXRFcnJvcihmYWxsYmFja0Vycm9yKX1gLFxuICAgICk7XG4gICAgZmFsbGJhY2sgPSBudWxsO1xuICB9XG5cbiAgY29uc3QgbmV3RXZlbnRDbGVhbnVwcyA9IGRpc3Bvc2VSZW5kZXJCaW5kaW5ncyhlZmZlY3REaXNwb3NlcnMsIGV2ZW50Q2xlYW51cHMpO1xuXG4gIGlmIChmYWxsYmFjayAhPSBudWxsKSB7XG4gICAgd2hpbGUgKHRhcmdldC5maXJzdENoaWxkKSB7XG4gICAgICB0YXJnZXQucmVtb3ZlQ2hpbGQodGFyZ2V0LmZpcnN0Q2hpbGQpO1xuICAgIH1cbiAgICB0YXJnZXQuYXBwZW5kQ2hpbGQocmVuZGVyVG9Eb20oZmFsbGJhY2ssIHVuZGVmaW5lZCwgZWZmZWN0RGlzcG9zZXJzLCBpbnN0YW5jZS5zaWduYWxSZWdpc3RyeSkpO1xuICB9XG5cbiAgcmV0dXJuIG5ld0V2ZW50Q2xlYW51cHM7XG59XG4iXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7Ozs7Ozs7OztDQVNDLEdBR0QsU0FBUyxXQUFXLFFBQVEsb0JBQW9CO0FBQ2hELFNBQVMsV0FBVyxRQUFRLDJCQUEyQjtBQUN2RCxTQUFTLFlBQVksUUFBUSwyQkFBMkI7QUFpQnhEOzs7Ozs7Q0FNQyxHQUNELE9BQU8sU0FBUyxzQkFDZCxlQUFnQyxFQUNoQyxhQUFnQztFQUVoQyxLQUFLLE1BQU0sS0FBSyxnQkFBaUI7RUFDakMsZ0JBQWdCLEtBQUs7RUFDckIsS0FBSyxNQUFNLEtBQUssY0FBZTtFQUMvQixPQUFPLEVBQUU7QUFDWDtBQUVBOzs7OztDQUtDLEdBQ0QsT0FBTyxTQUFTLG1CQUNkLFFBQXFCLEVBQ3JCLGVBQWdDLEVBQ2hDLGFBQWdDLEVBQ2hDLEtBQXVCO0VBRXZCLE1BQU0sbUJBQW1CLHNCQUFzQixpQkFBaUI7RUFFaEUsTUFBTSxTQUFTLFNBQVMsTUFBTTtFQUM5QixNQUFNLEdBQUcsQ0FBQztFQUVWLE1BQU0sT0FBTztFQUNiLE1BQU8sS0FBSyxVQUFVLENBQUU7SUFDdEIsS0FBSyxXQUFXLENBQUMsS0FBSyxVQUFVO0VBQ2xDO0VBRUEsSUFBSSxVQUFVLE1BQU07SUFDbEIsS0FBSyxXQUFXLENBQUMsWUFBWSxRQUFRLFdBQVcsaUJBQWlCLFNBQVMsY0FBYztFQUMxRjtFQUVBLE9BQU87QUFDVDtBQUVBOzs7OztDQUtDLEdBQ0QsT0FBTyxTQUFTLHFCQUNkLFFBQXFCLEVBQ3JCLGVBQWdDLEVBQ2hDLGFBQWdDLEVBQ2hDLEtBQXVCO0VBRXZCLE1BQU0sT0FBTyxTQUFTLFVBQVU7RUFDaEMsSUFBSSxDQUFDLE1BQU0sT0FBTztFQUVsQixNQUFNLG1CQUFtQixzQkFBc0IsaUJBQWlCO0VBRWhFLE1BQU0sU0FBUyxTQUFTLE1BQU07RUFDOUIsTUFBTSxHQUFHLENBQUM7RUFFVixJQUFJLFVBQVUsTUFBTTtJQUNsQixNQUFPLEtBQUssVUFBVSxDQUFFO01BQ3RCLEtBQUssV0FBVyxDQUFDLEtBQUssVUFBVTtJQUNsQztJQUNBLEtBQUssV0FBVyxDQUFDLFlBQVksUUFBUSxXQUFXLGlCQUFpQixTQUFTLGNBQWM7RUFDMUY7RUFFQSxPQUFPO0FBQ1Q7QUFFQTs7Ozs7Q0FLQyxHQUNELE9BQU8sU0FBUyxvQkFDZCxRQUFxQixFQUNyQixLQUFjLEVBQ2QsZUFBZ0MsRUFDaEMsYUFBZ0MsRUFDaEMsYUFBK0M7RUFFL0MsTUFBTSxPQUFPLFNBQVMsV0FBVztFQUNqQyxNQUFNLGFBQWEsS0FBSyxVQUFVLEtBQUs7RUFFdkMsSUFBSSxDQUFDLFNBQVMsVUFBVSxJQUFJLENBQUMsWUFBWTtJQUN2QyxTQUFTLGdCQUFnQjtFQUMzQjtFQUVBLE1BQU0sU0FBUyxhQUFjLFdBQTJCLFNBQVMsVUFBVTtFQUMzRSxJQUFJLENBQUMsUUFBUSxPQUFPLEVBQUU7RUFFdEIsSUFBSTtFQUNKLElBQUk7SUFDRixXQUFXLGNBQWM7RUFDM0IsRUFBRSxPQUFPLGVBQWU7SUFDdEIsYUFBYSxPQUFPLEtBQUssQ0FDdkIsQ0FBQyxDQUFDLEVBQUUsU0FBUyxPQUFPLENBQUMsV0FBVyxHQUFHLHdCQUF3QixFQUFFLFlBQVksZ0JBQWdCO0lBRTNGLFdBQVc7RUFDYjtFQUVBLE1BQU0sbUJBQW1CLHNCQUFzQixpQkFBaUI7RUFFaEUsSUFBSSxZQUFZLE1BQU07SUFDcEIsTUFBTyxPQUFPLFVBQVUsQ0FBRTtNQUN4QixPQUFPLFdBQVcsQ0FBQyxPQUFPLFVBQVU7SUFDdEM7SUFDQSxPQUFPLFdBQVcsQ0FBQyxZQUFZLFVBQVUsV0FBVyxpQkFBaUIsU0FBUyxjQUFjO0VBQzlGO0VBRUEsT0FBTztBQUNUIn0=

package/src/open-element.d.ts

@@ -0,0 +1,176 @@
+import type { StyleSheetLike } from '@openelement/protocol/style-sheet';
+import type { VNode } from '@openelement/protocol/vnode';
+import type { Signal } from '@openelement/protocol/signal';
+/**
+ * SSR-safe base class for OpenElement.
+ *
+ * In browser: extends HTMLElement directly.
+ * In SSR: assigns a minimal stub to globalThis.HTMLElement so the entire
+ * dependency graph shares the same base class.
+ */ declare const _Base: any;
+/**
+ * Zero-dependency Custom Element base class for DSD rendering.
+ *
+ * Provides DSD detection, CSR fallback, event hydration, and style management
+ * without any framework dependency (no Lit, no reactive-element).
+ *
+ * Subclasses MUST override `render(): VNode | null`.
+ */ export declare class OpenElement extends _Base {
+  /** Component stylesheets (SSR-safe - StyleSheet delegates to native CSSStyleSheet in browser). */ static styles?: StyleSheetLike | StyleSheetLike[];
+  /** Rendering mode. Defaults to shadow/DSD; light DOM is explicit opt-in. */ static renderMode?: 'shadow' | 'light';
+  /** v0.25.0: Page head metadata. SSG reads this to inject <title> and <meta> tags. */ static head?: {
+    title?: string;
+    description?: string;
+    ogImage?: string;
+  };
+  /** @internal — use openPipeline({ island: { upgradeStrategy } }) instead */ static client?: {
+    strategy?: 'load' | 'idle' | 'visible' | 'only';
+  };
+  /**
+   * Attributes that trigger attributeChangedCallback.
+   * Subclasses override this to declare reactive attributes.
+   */ static observedAttributes?: string[];
+  /**
+   * Whether to delegate focus within the shadow root.
+   * When true, attachShadow is called with `delegatesFocus: true`.
+   */ static delegatesFocus?: boolean;
+  /**
+   * Whether this element participates in form submission.
+   * When true, ElementInternals are attached in connectedCallback.
+   */ static formAssociated?: boolean;
+  /**
+   * Signal registry for attribute-based hydration (ADR-0065).
+   * Maps signal names → signal objects. Built by registerSignal()
+   * in component constructors, consumed during hydration.
+   *
+   * Exposed internally for render helper modules.
+   */ signalRegistry: Map<string, Signal<unknown>>;
+  /**
+   * Register a signal for hydration by name.
+   * Call in constructor: this.registerSignal('count', this.#count);
+   */ protected registerSignal(name: string, sig: Signal<unknown>): void;
+  /** Reactive route parameters. Updates automatically on SPA navigation. */ get params(): Record<string, string>;
+  set params(value: Record<string, string>);
+  /** ElementInternals for form-associated custom elements */ protected _internals?: ElementInternals;
+  /**
+   * Create or reuse the shadow root.
+   *
+   * DSD detection: if `this.shadowRoot` already exists and has nodes,
+   * the browser pre-populated it from a <template shadowrootmode> tag.
+   * In that case we mark `_dsdHydrated = true` and return the existing root.
+   *
+   * CSR fallback: if no shadow root exists, we call `attachShadow()`. If an
+   * empty shadow root already exists, we reuse it and let connectedCallback()
+   * populate it from render().
+   *
+   * @returns The existing or newly created ShadowRoot.
+   */ createRenderRoot(): ShadowRoot | this;
+  private _applyStyles: any;
+  /**
+   * Lifecycle: called when the element is connected to the DOM.
+   *
+   * DSD path (_dsdHydrated = true):
+   *   - Calls _hydrateEvents() to bind declarative events on existing DOM.
+   *
+   * CSR path (_dsdHydrated = false):
+   *   - Calls createRenderRoot() if no shadow root exists.
+   *   - Renders this.render() through the VNode DOM renderer.
+   *
+   * If formAssociated is true, ElementInternals are attached.
+   */ connectedCallback(): void;
+  private _renderOrHydrate: any;
+  private _hydrateSignals: any;
+  private _hydrateExistingDom: any;
+  /**
+   * v0.23.0: Hook called after DSD hydration completes.
+   *
+   * Subclasses override this instead of relying on fragile
+   * `super.connectedCallback()` call order. At this point the
+   * shadow DOM is populated from DSD and declarative events
+   * (@click, @keydown) are bound.
+   *
+   * No-op by default.
+   */ protected onDsdHydrated(): void;
+  /**
+   * v0.23.0: Hook called after CSR first render completes.
+   *
+   * Subclasses override this for post-render initialization
+   * that depends on the shadow DOM being populated. At this
+   * point render() has been called and declarative events
+   * are bound.
+   *
+   * No-op by default.
+   */ protected onCsrRendered(): void;
+  /**
+   * v0.40.0: Client-side activation hook.
+   *
+   * Called once after the element is connected, the shadow root
+   * is ready, and any DSD hydration or CSR rendering has completed.
+   * This is the right place for framework hydration (Preact, React,
+   * Vue, Lit) to take over the shadow DOM.
+   *
+   * Default implementation is a no-op. Subclasses override this to
+   * hydrate or render framework components into the shadow root.
+   */ protected clientActivate(): void;
+  /**
+   * Hook called when the unified client render/hydrate path throws.
+   * Subclasses may return a VNode fallback.
+   */ protected onRenderError(error: unknown): VNode | null;
+  private _renderErrorFallback: any;
+  /**
+   * Lifecycle: called when the element is disconnected from the DOM.
+   * Aborts all hydration event listeners for cleanup.
+   */ disconnectedCallback(): void;
+  /**
+   * Lifecycle: called when an observed attribute changes.
+   *
+   * Base implementation is a no-op. Subclasses override this to react
+   * to attribute changes, typically by calling `this.render()` to update
+   * the shadow DOM.
+   *
+   * @param name - Attribute name (lowercase).
+   * @param oldValue - Previous value, or null if the attribute was not set.
+   * @param newValue - New value, or null if the attribute was removed.
+   */ attributeChangedCallback(_name: string, _oldValue: string | null, _newValue: string | null): void;
+  /**
+   * Re-render the shadow DOM from `render()` and re-bind declarative events.
+   *
+   * OpenElement intentionally does not include a reactive scheduler. Components
+   * with local state can call this method after state changes instead of
+   * duplicating renderToDom() and event hydration.
+   */ update(): void;
+  /**
+   * ReactiveController-compatible update hook.
+   *
+   * Async state controllers call this method when state changes. Keeping this
+   * tiny alias lets OpenElement host controllers without inheriting Lit or a
+   * scheduler.
+   */ requestUpdate(): void;
+  private _renderIntoLightDom: any;
+  private _renderIntoShadowRoot: any;
+  /**
+   * Read locale from JS property (set by SSR injectProps) first,
+   * then HTML attribute, then fallback to provided default.
+   *
+   * SSR injectProps() sets camelCase JS properties (e.g. this.locale = 'en')
+   * but getAttribute() only reads HTML attributes, which remain null.
+   * This method resolves the mismatch by checking JS property first.
+   *
+   * @param fallback - Default value when neither source has a value. Defaults to 'en'.
+   */ protected _getLocale(fallback?: string): string;
+  /**
+   * Return Shadow DOM content as a VNode.
+   *
+   * Subclasses MUST override this method. During SSR, rendered content is
+   * wrapped in a <template shadowrootmode="open"> tag. During CSR, VNode values
+   * are rendered via renderToDom() with event binding and signal tracking.
+   *
+   * @returns VNode for the shadow DOM content, or null for empty content.
+   */ render(): VNode | null;
+}
+/** OpenElement constructor with framework-convention static properties. */ export interface OpenElementComponentConstructor extends CustomElementConstructor {
+  styles?: StyleSheetLike | StyleSheetLike[];
+  tagName?: string;
+  renderMode?: 'shadow' | 'light';
+  observedAttributes?: string[];
+}