@context-action/lit-ui 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Change Log
+
+## [0.1.1] (2026-10-23)
+
+### Fixed
+
+- `hydrateLit(host.shadowRoot, host)` now finds `lit-part` markers anywhere
+  under the shadow root instead of assuming they are direct siblings of the
+  first node. Declarative shadow roots with `static styles` are adopted instead
+  of appending a second client render.
+- If a client render already appended a duplicate tree before `hydrateLit` runs,
+  the server root part is isolated, the client tree is removed, and the server
+  tree is re-adopted. Final item counts and server node identity are preserved.
+
+### Tests
+
+- Added static-styles + three-item DSD hydration regression coverage in jsdom
+  and Chromium, including the late `hydrateLit` after first-update scenario.
+
+## [0.1.0] (2026-10-23)
+
+Published to npm on 2026-10-23. `latest` and `next` resolve to `0.1.0`.
+
+### Added
+
+- Initial public release of the Lit UI primitives and integrations.
+- `FormAssociatedLitElement` with ElementInternals, constraint validation,
+  form value management, and reset/state-restore lifecycle hooks.
+- W3C `@lit/context` tokens, providers, and controllers for stores and action
+  registers across Shadow DOM boundaries.
+- `createLitElementBridge` for React 18/19 with direct complex-property
+  assignment, bridge-owned property removal, handler-identity event
+  reconciliation, StrictMode safety, attribute passthrough, and OOP facade
+  handles through `createHandle` / `createElementFacade`.
+- `@context-action/lit-ui/ssr` with `renderLitElement`, `renderLitTemplate`,
+  reflected host attributes, light DOM/slot preservation, and async renderer
+  variants.
+- `@context-action/lit-ui/hydrate` as a client-only entry with Lit hydration
+  support, declarative shadow root adoption, template hydration, and no server
+  renderer dependency.
+- Reference `LitQuantityStepper` and `LitCartBadge` custom elements.
+- `ControllerScope` re-export from `@context-action/lit`.
+
+### Verification
+
+- Unit, stress, React 18 consumer matrix, processless/Edge runtime, and Chromium
+  declarative-shadow-DOM hydration contracts run through `pnpm check:lit`,
+  `pnpm verify:lit-react-compatibility`, and `pnpm --filter @context-action/lit-ui test:browser`.
+- Package exports and tarballs are part of the public package verification,
+  including a packed consumer install smoke.
+
+### Changed
+
+- Tooling updated to React 19.3.1 for the development matrix, Vitest `5.0.5`,
+  jsdom `30.1.3`, Vite `8.3.5`, and tsdown `0.23.1`; TypeScript remains on the
+  repository's `6.0.3` baseline.
+- Reference custom elements use idempotent registration so ESM and CJS builds
+  can be loaded in the same process without a duplicate-definition error.
+
+### Documentation
+
+- README and `docs/` cover DOM ownership, ReactiveController architecture, FACE,
+  W3C context communication, interface standards, SSR, hydration, and the React
+  bridge contract.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2024 Jun Woo Bang
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,118 @@
-# Temporary Holding Version
+# @context-action/lit-ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Web Component primitives, Form-Associated Custom Elements (FACE), W3C Context Protocol (`@lit/context`) dependency injection, and React 18/19 custom element bridge for the Context-Action state management framework.
+
+## Responsibilities
+
+- **`FormAssociatedLitElement`**: Abstract base class extending `LitElement` with full Form-Associated Custom Elements (FACE) support (`ElementInternals`, standard validation constraints, `setFormValue()`, and leak-free `formResetCallback()` coordination).
+- **W3C Context Protocol Integration**: Global context tokens (`actionRegisterContext`, `actionDispatcherContext`, `createStoreContext`), imperative providers (`provideStore`, `provideActionRegister`, `provideActionDispatcher`), and reactive context controllers (`ContextStoreController`, `ContextActionController`) crossing Shadow DOM boundaries.
+- **`createLitElementBridge`**: React 18/19 custom element bridge with direct property assignment (bypassing attribute stringification), property removal, handler-identity event reconciliation, OOP facade handles, and ref forwarding.
+- **`@context-action/lit-ui/ssr`**: Lit SSR renderers (`renderLitElement`, `renderLitTemplate`) and client hydration (`hydrateLit`) that preserve `part`, `data-*`, and declarative shadow roots.
+- **`@context-action/lit-ui/hydrate`**: Client-only hydration entry. It loads Lit hydration support and never imports the server renderer.
+- **`ControllerScope`**: Re-exported from `@context-action/lit` for LIFO ReactiveController and cleanup disposal.
+
+## React Bridge
+
+```tsx
+import { createElementFacade, createLitElementBridge } from '@context-action/lit-ui';
+
+type TimelineHandle = Pick<TimelineElement, 'focusItem' | 'scrollTo' | 'commitSelection'>;
+
+const ReactTimeline = createLitElementBridge<TimelineProps, TimelineElement, TimelineHandle>({
+  tagName: 'st-timeline',
+  properties: ['input', 'set'],
+  events: { onSelectionChange: 'selection-change' },
+  createHandle: createElementFacade<
+    TimelineElement,
+    readonly ['focusItem', 'scrollTo', 'commitSelection']
+  >(['focusItem', 'scrollTo', 'commitSelection']),
+});
+```
+
+- Properties removed from props are reset to `undefined`; read-only properties keep their adapter-owned value.
+- Event listeners are reconciled by handler identity, so a re-render with the same handler performs zero `addEventListener` calls.
+- `createHandle` exposes only the declared facade methods; raw element internals stay private.
+- Props not listed in `properties`/`events` continue to render as DOM attributes.
+
+## SSR and hydration
+
+```ts
+// Server (Node/Edge/Worker)
+import { renderLitElement, renderLitTemplate } from '@context-action/lit-ui/ssr';
+
+const markup = renderLitElement(timelineElement);
+// or: const markup = renderLitTemplate(html`<st-timeline></st-timeline>`);
+
+// Client — import before defining Lit elements so hydration support is installed.
+import { hydrateLit } from '@context-action/lit-ui/hydrate';
+
+hydrateLit(container, timelineElement);
+```
+
+The `./ssr` entry requires `@lit-labs/ssr` and `@lit-labs/ssr-client` (optional peers; install them in server/catalog deployments).
+`renderLitElement` requires the element to be registered with `customElements.define()` first.
+Reflected reactive properties are serialized as host attributes, and light DOM children are included by default so `<slot>` projection survives SSR (`includeLightDom: false` opts out).
+`hydrateLit` re-exports from `./ssr` for compatibility, but `./hydrate` keeps the server renderer out of client bundles.
+
+## Install
+
+```bash
+pnpm add @context-action/lit-ui @context-action/lit lit @lit/context
+# Optional: SSR/catalog deployments
+pnpm add @lit-labs/ssr @lit-labs/ssr-client
+```
+
+`lit`, `@lit/context`, and `react` are peer dependencies. `react` is optional
+and only needed for `createLitElementBridge`. The SSR peers are optional and
+only needed for `@context-action/lit-ui/ssr`.
+
+The SSR entry does not read `window` or `document` at module evaluation time,
+and builds to both ESM and CJS.
+`renderLitTemplateAsync` / `renderLitElementAsync` are available for asynchronous element renderers.
+
+## Verification
+
+```bash
+pnpm check:lit                                  # build + type-check + unit + edge runtime
+pnpm verify:lit-react-compatibility             # React 18 consumer matrix
+pnpm --filter @context-action/lit-ui test:browser # Chromium DSD hydration contract
+```
+
+## Status
+
+Public package. `0.1.1` is the current patch release candidate for the
+static-styles hydration fix; `0.1.0` remains the last published version until
+the candidate/promotion workflows complete.
+
+- https://www.npmjs.com/package/@context-action/lit-ui
+- Release plan: [`releases/LIT_PUBLIC_0.1.1.md`](../../releases/LIT_PUBLIC_0.1.1.md)
+
+Requires Node.js `>=24.11.0`.
+
+## Architecture
+
+```text
+┌────────────────────────────────────────────────────────┐
+│ React 18/19 Host Application                           │
+│   └── createLitElementBridge(CustomElement)            │
+└───────────────────────────┬────────────────────────────┘
+                            │ (Direct Properties & Custom Events)
+┌───────────────────────────▼────────────────────────────┐
+│ Custom Element (LitElement / FormAssociatedLitElement)  │
+│   ├── #shadow-root (Encapsulated CSS & DOM)            │
+│   ├── ElementInternals (Native Form Participation)     │
+│   ├── ContextStoreController / ContextActionController │
+│   │     ▲                                              │
+│   │     │ (W3C Context Protocol: context-request)       │
+│   └─────┴──────────────────────────────────────────────┘
+```
+
+## Documentation
+
+- [01. DOM Ownership & Shadow DOM Isolation](docs/01-dom-ownership.md)
+- [02. ReactiveController vs React Hooks & 3-Layer Architecture](docs/02-reactive-controller-vs-hooks.md)
+- [03. Form-Associated Custom Elements (FACE) & ElementInternals](docs/03-form-associated-elements.md)
+- [04. W3C Context Protocol & Micro-Frontend Communication](docs/04-micro-frontend-communication.md)
+- [05. Interface Design & Baseline State Management Standards](docs/05-interface-and-state-management-standards.md)
+- [06. SSR and Hydration Entry](docs/06-ssr-hydration.md)
+- [07. Public Release and Verification](docs/07-release-and-verification.md)

package/dist/hydrate.cjs

@@ -0,0 +1,218 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let lit = require("lit");
+require("@lit-labs/ssr-client/lit-element-hydrate-support.js");
+let _lit_labs_ssr_client = require("@lit-labs/ssr-client");
+// src/hydrate.ts
+/**
+* @fileoverview Client-only hydration entry (`@context-action/lit-ui/hydrate`).
+*
+* This module intentionally imports only `@lit-labs/ssr-client` and the Lit
+* runtime, never the server renderer. Client bundles that only need
+* `hydrateLit()` can avoid pulling `@lit-labs/ssr` into the browser graph.
+*
+* @implements view-layer
+* @implements web-component-primitive
+* @memberof core-concepts
+*/
+const COMMENT_NODE = 8;
+const DOCUMENT_FRAGMENT_NODE = 11;
+function hasLitPartMarker(root) {
+	const document = root.ownerDocument ?? root.host?.ownerDocument ?? null;
+	if (document && typeof document.createTreeWalker === "function") {
+		const walker = document.createTreeWalker(root, 128);
+		while (walker.nextNode()) if (walker.currentNode.data.startsWith("lit-part")) return true;
+		return false;
+	}
+	for (let node = root.firstChild; node; node = node.nextSibling) {
+		if (node.nodeType === COMMENT_NODE && node.data.startsWith("lit-part")) return true;
+		if (node.nodeType === 1 && hasLitPartMarker(node)) return true;
+	}
+	return false;
+}
+function findServerHost(root, element) {
+	const tagName = element.localName;
+	if (!tagName) return null;
+	if (root.nodeType === DOCUMENT_FRAGMENT_NODE && "host" in root && root.host === element) return null;
+	if (root.nodeType === 1 && root.localName === tagName) return root;
+	return root.querySelector?.(tagName) ?? null;
+}
+function isHydrationSupportInstalled() {
+	const shadow = {};
+	const probe = { shadowRoot: shadow };
+	const createRenderRoot = lit.LitElement.prototype.createRenderRoot;
+	try {
+		return createRenderRoot.call(probe) === shadow;
+	} catch {
+		return false;
+	}
+}
+function partStartNode(part) {
+	return part?._$startNode ?? part?._$AA ?? null;
+}
+function isServerRootPart(part) {
+	const start = partStartNode(part);
+	return start?.nodeType === COMMENT_NODE && start.data.startsWith("lit-part");
+}
+/**
+* When a client render appended a separate tree beside the server DSD tree,
+* keep only the server root part (plus preceding static style tags), remove the
+* client anchors/children, and re-adopt the surviving server tree.
+*/
+function isolateServerTree(shadow) {
+	const children = Array.from(shadow.childNodes);
+	const rootIndex = children.findIndex((node) => node.nodeType === COMMENT_NODE && node.data.startsWith("lit-part"));
+	if (rootIndex < 0) return false;
+	let beginIndex = rootIndex;
+	while (beginIndex > 0) {
+		const previous = children[beginIndex - 1];
+		if (previous.nodeType === 1 && previous.localName === "style") {
+			beginIndex -= 1;
+			continue;
+		}
+		break;
+	}
+	let depth = 0;
+	let endIndex = -1;
+	for (let index = rootIndex; index < children.length; index += 1) {
+		const node = children[index];
+		if (node.nodeType !== COMMENT_NODE) continue;
+		const data = node.data;
+		if (data.startsWith("lit-part")) depth += 1;
+		else if (data.startsWith("/lit-part")) {
+			depth -= 1;
+			if (depth === 0) {
+				endIndex = index;
+				break;
+			}
+		}
+	}
+	if (endIndex < 0) return false;
+	for (let index = children.length - 1; index > endIndex; index -= 1) children[index].parentNode?.removeChild(children[index]);
+	for (let index = 0; index < beginIndex; index += 1) children[index].parentNode?.removeChild(children[index]);
+	return true;
+}
+function adoptServerShadow(host, shadow) {
+	host._$needsHydration = false;
+	host._$AG = false;
+	if (isolateServerTree(shadow)) {
+		delete shadow._$litPart$;
+		try {
+			const rendered = host.render();
+			(0, _lit_labs_ssr_client.hydrate)(rendered, shadow);
+			host.requestUpdate();
+			return;
+		} catch {}
+	}
+	shadow.replaceChildren();
+	delete shadow._$litPart$;
+	host.requestUpdate();
+}
+function hydrateHost(host) {
+	const shadow = host.shadowRoot;
+	if (!shadow) {
+		host.requestUpdate();
+		return;
+	}
+	const hydrationSupportInstalled = isHydrationSupportInstalled();
+	if (!hydrationSupportInstalled) Object.defineProperty(host, "createRenderRoot", {
+		configurable: true,
+		value: () => shadow
+	});
+	const livePart = shadow._$litPart$;
+	if (livePart !== void 0) {
+		if (hasLitPartMarker(shadow) && !isServerRootPart(livePart)) {
+			adoptServerShadow(host, shadow);
+			return;
+		}
+		host.requestUpdate();
+		return;
+	}
+	if (!hasLitPartMarker(shadow)) {
+		shadow.replaceChildren();
+		host.requestUpdate();
+		return;
+	}
+	if (hydrationSupportInstalled) {
+		host.requestUpdate();
+		return;
+	}
+	const rendered = host.render();
+	(0, _lit_labs_ssr_client.hydrate)(rendered, shadow);
+	host.requestUpdate();
+}
+function upgradeServerHost(host, element) {
+	const tagName = element.localName;
+	const registry = globalThis.customElements;
+	if (!registry) throw new Error("hydrateLit() requires a DOM environment with customElements.");
+	if (!registry.get(tagName)) registry.define(tagName, element.constructor);
+	const existingShadow = host.shadowRoot;
+	if (existingShadow && !isHydrationSupportInstalled()) Object.defineProperty(host, "createRenderRoot", {
+		configurable: true,
+		value: () => existingShadow
+	});
+	const elementConstructor = element.constructor;
+	if (host instanceof elementConstructor) {
+		hydrateHost(host);
+		return;
+	}
+	registry.upgrade(host);
+	if (host instanceof elementConstructor) hydrateHost(host);
+}
+/**
+* Hydrates server-produced markup on the client.
+*
+* Supported modes:
+* 1. `root` is an element's own shadow root (or contains the Lit template
+*    markers produced by `renderLitTemplate`): the element's current template is
+*    hydrated into that root, preserving existing DOM and attaching event parts.
+* 2. `root` contains a server-rendered custom element host for the same tag:
+*    the host is upgraded so its controllers and attributes connect.
+* 3. `root` is empty: the element is mounted and rendered normally.
+*
+* The function never reads a global `document`; it operates only on the supplied
+* root and element.
+*/
+function hydrateLit(root, element) {
+	if (!root || typeof root !== "object") throw new TypeError("hydrateLit() requires an Element or ShadowRoot.");
+	if (!element || typeof element !== "object") throw new TypeError("hydrateLit() requires a LitElement instance.");
+	const serverHost = findServerHost(root, element);
+	if (serverHost && serverHost !== element) {
+		upgradeServerHost(serverHost, element);
+		return;
+	}
+	if (root.nodeType === DOCUMENT_FRAGMENT_NODE && "host" in root && root.host === element) {
+		const shadow = root;
+		const livePart = shadow._$litPart$;
+		if (livePart === void 0) {
+			Object.defineProperty(element, "createRenderRoot", {
+				configurable: true,
+				value: () => shadow
+			});
+			if (hasLitPartMarker(shadow)) {
+				const rendered = element.render();
+				(0, _lit_labs_ssr_client.hydrate)(rendered, shadow);
+			} else shadow.replaceChildren();
+		} else if (hasLitPartMarker(shadow) && !isServerRootPart(livePart)) {
+			adoptServerShadow(element, shadow);
+			return;
+		}
+		element._$needsHydration = false;
+		element._$AG = false;
+		element.requestUpdate();
+		return;
+	}
+	if (hasLitPartMarker(root)) {
+		if (root._$litPart$ !== void 0) {
+			element.requestUpdate();
+			return;
+		}
+		const rendered = element.render();
+		(0, _lit_labs_ssr_client.hydrate)(rendered, root);
+		return;
+	}
+	if (root !== element && !element.isConnected) root.append(element);
+	element.requestUpdate();
+}
+exports.hydrateLit = hydrateLit;
+
+//# sourceMappingURL=hydrate.cjs.map

package/dist/hydrate.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydrate.cjs","names":["LitElement"],"sources":["../src/hydrate.ts"],"sourcesContent":["/**\n * @fileoverview Client-only hydration entry (`@context-action/lit-ui/hydrate`).\n *\n * This module intentionally imports only `@lit-labs/ssr-client` and the Lit\n * runtime, never the server renderer. Client bundles that only need\n * `hydrateLit()` can avoid pulling `@lit-labs/ssr` into the browser graph.\n *\n * @implements view-layer\n * @implements web-component-primitive\n * @memberof core-concepts\n */\n\nimport '@lit-labs/ssr-client/lit-element-hydrate-support.js';\nimport { LitElement } from 'lit';\nimport { hydrate } from '@lit-labs/ssr-client';\n\nconst COMMENT_NODE = 8;\nconst DOCUMENT_FRAGMENT_NODE = 11;\n\nfunction hasLitPartMarker(root: Element | ShadowRoot): boolean {\n  const document = root.ownerDocument\n    ?? (root as ShadowRoot).host?.ownerDocument\n    ?? null;\n  if (document && typeof document.createTreeWalker === 'function') {\n    const walker = document.createTreeWalker(root, 128 /* NodeFilter.SHOW_COMMENT */);\n    while (walker.nextNode()) {\n      if ((walker.currentNode as Comment).data.startsWith('lit-part')) {\n        return true;\n      }\n    }\n    return false;\n  }\n\n  // Defensive fallback for environments without TreeWalker.\n  for (let node = root.firstChild; node; node = node.nextSibling) {\n    if (\n      node.nodeType === COMMENT_NODE &&\n      (node as Comment).data.startsWith('lit-part')\n    ) {\n      return true;\n    }\n    if (node.nodeType === 1 && hasLitPartMarker(node as Element)) {\n      return true;\n    }\n  }\n  return false;\n}\n\nfunction findServerHost(\n  root: Element | ShadowRoot,\n  element: LitElement,\n): Element | null {\n  const tagName = element.localName;\n  if (!tagName) return null;\n\n  // A ShadowRoot owned by the element is a render target, not a host container.\n  if (\n    root.nodeType === DOCUMENT_FRAGMENT_NODE &&\n    'host' in root &&\n    root.host === element\n  ) {\n    return null;\n  }\n\n  if (root.nodeType === 1 && (root as Element).localName === tagName) {\n    return root as Element;\n  }\n\n  return root.querySelector?.(tagName) ?? null;\n}\n\nfunction isHydrationSupportInstalled(): boolean {\n  const shadow = {};\n  const probe = { shadowRoot: shadow } as unknown as LitElement;\n  const createRenderRoot = (\n    LitElement.prototype as unknown as {\n      createRenderRoot(this: LitElement): unknown;\n    }\n  ).createRenderRoot;\n  try {\n    return createRenderRoot.call(probe) === shadow;\n  } catch {\n    return false;\n  }\n}\n\ninterface LitPartLike {\n  _$startNode?: Node | null;\n  _$endNode?: Node | null;\n  _$AA?: Node | null;\n  _$AB?: Node | null;\n}\n\nfunction partStartNode(part: LitPartLike | undefined): Node | null {\n  return part?._$startNode ?? part?._$AA ?? null;\n}\n\nfunction partEndNode(part: LitPartLike | undefined): Node | null {\n  return part?._$endNode ?? part?._$AB ?? null;\n}\n\nfunction isServerRootPart(part: LitPartLike | undefined): boolean {\n  const start = partStartNode(part);\n  return (\n    start?.nodeType === COMMENT_NODE &&\n    (start as Comment).data.startsWith('lit-part')\n  );\n}\n\n/**\n * When a client render appended a separate tree beside the server DSD tree,\n * keep only the server root part (plus preceding static style tags), remove the\n * client anchors/children, and re-adopt the surviving server tree.\n */\nfunction isolateServerTree(shadow: ShadowRoot): boolean {\n  const children = Array.from(shadow.childNodes);\n  const rootIndex = children.findIndex(\n    node => node.nodeType === COMMENT_NODE && (node as Comment).data.startsWith('lit-part'),\n  );\n  if (rootIndex < 0) return false;\n\n  let beginIndex = rootIndex;\n  while (beginIndex > 0) {\n    const previous = children[beginIndex - 1]!;\n    if (previous.nodeType === 1 && (previous as Element).localName === 'style') {\n      beginIndex -= 1;\n      continue;\n    }\n    break;\n  }\n\n  let depth = 0;\n  let endIndex = -1;\n  for (let index = rootIndex; index < children.length; index += 1) {\n    const node = children[index]!;\n    if (node.nodeType !== COMMENT_NODE) continue;\n    const data = (node as Comment).data;\n    if (data.startsWith('lit-part')) {\n      depth += 1;\n    } else if (data.startsWith('/lit-part')) {\n      depth -= 1;\n      if (depth === 0) {\n        endIndex = index;\n        break;\n      }\n    }\n  }\n  if (endIndex < 0) return false;\n\n  for (let index = children.length - 1; index > endIndex; index -= 1) {\n    children[index]!.parentNode?.removeChild(children[index]!);\n  }\n  for (let index = 0; index < beginIndex; index += 1) {\n    children[index]!.parentNode?.removeChild(children[index]!);\n  }\n  return true;\n}\n\nfunction adoptServerShadow(host: LitElement, shadow: ShadowRoot): void {\n  // Clear Lit hydration support flags so the following requestUpdate does not\n  // adopt the same tree a second time.\n  (host as unknown as { _$needsHydration?: boolean })._$needsHydration = false;\n  (host as unknown as { _$AG?: boolean })._$AG = false;\n\n  if (isolateServerTree(shadow)) {\n    delete (shadow as ShadowRoot & { _$litPart$?: unknown })._$litPart$;\n    try {\n      const rendered = (host as unknown as { render(): unknown }).render();\n      hydrate(rendered, shadow);\n      host.requestUpdate();\n      return;\n    } catch {\n      // Fall through to a clean client render when the server tree cannot be\n      // adopted (for example after an incompatible template change).\n    }\n  }\n\n  shadow.replaceChildren();\n  delete (shadow as ShadowRoot & { _$litPart$?: unknown })._$litPart$;\n  host.requestUpdate();\n}\n\nfunction hydrateHost(host: LitElement): void {\n  const shadow = host.shadowRoot;\n  if (!shadow) {\n    host.requestUpdate();\n    return;\n  }\n\n  const hydrationSupportInstalled = isHydrationSupportInstalled();\n  if (!hydrationSupportInstalled) {\n    Object.defineProperty(host, 'createRenderRoot', {\n      configurable: true,\n      value: () => shadow,\n    });\n  }\n\n  const livePart = (shadow as ShadowRoot & { _$litPart$?: LitPartLike })._$litPart$;\n  if (livePart !== undefined) {\n    if (hasLitPartMarker(shadow) && !isServerRootPart(livePart)) {\n      adoptServerShadow(host, shadow);\n      return;\n    }\n    host.requestUpdate();\n    return;\n  }\n\n  if (!hasLitPartMarker(shadow)) {\n    // Server markup without lit-html markers cannot be hydrated. Clear it and\n    // force the first client render into this shadow root without asking Lit's\n    // hydration support to adopt a non-lit tree.\n    shadow.replaceChildren();\n    host.requestUpdate();\n    return;\n  }\n\n  // Lit's official hydration support patches createRenderRoot/update and\n  // adopts the declarative shadow root on the first update. Running hydrate()\n  // ourselves would make support hydrate the same container twice.\n  if (hydrationSupportInstalled) {\n    host.requestUpdate();\n    return;\n  }\n\n  const rendered = (host as unknown as { render(): unknown }).render();\n  hydrate(rendered, shadow);\n  host.requestUpdate();\n}\n\nfunction upgradeServerHost(host: Element, element: LitElement): void {\n  const tagName = element.localName;\n  const registry = globalThis.customElements;\n  if (!registry) {\n    throw new Error('hydrateLit() requires a DOM environment with customElements.');\n  }\n\n  if (!registry.get(tagName)) {\n    registry.define(tagName, element.constructor as CustomElementConstructor);\n  }\n\n  // A declarative shadow root already contains the server template. When Lit's\n  // hydration support is not installed, prevent the first update from calling\n  // attachShadow() on the same host. When support is installed, its patched\n  // createRenderRoot already does this and must remain in control.\n  const existingShadow = host.shadowRoot;\n  if (existingShadow && !isHydrationSupportInstalled()) {\n    Object.defineProperty(host, 'createRenderRoot', {\n      configurable: true,\n      value: () => existingShadow,\n    });\n  }\n\n  const elementConstructor = element.constructor as unknown as { new (): LitElement };\n  if (host instanceof elementConstructor) {\n    hydrateHost(host);\n    return;\n  }\n\n  registry.upgrade(host);\n  if (host instanceof elementConstructor) {\n    hydrateHost(host);\n  }\n}\n\n/**\n * Hydrates server-produced markup on the client.\n *\n * Supported modes:\n * 1. `root` is an element's own shadow root (or contains the Lit template\n *    markers produced by `renderLitTemplate`): the element's current template is\n *    hydrated into that root, preserving existing DOM and attaching event parts.\n * 2. `root` contains a server-rendered custom element host for the same tag:\n *    the host is upgraded so its controllers and attributes connect.\n * 3. `root` is empty: the element is mounted and rendered normally.\n *\n * The function never reads a global `document`; it operates only on the supplied\n * root and element.\n */\nexport function hydrateLit(root: Element | ShadowRoot, element: LitElement): void {\n  if (!root || typeof root !== 'object') {\n    throw new TypeError('hydrateLit() requires an Element or ShadowRoot.');\n  }\n  if (!element || typeof element !== 'object') {\n    throw new TypeError('hydrateLit() requires a LitElement instance.');\n  }\n\n  const serverHost = findServerHost(root, element);\n  if (serverHost && serverHost !== element) {\n    upgradeServerHost(serverHost, element);\n    return;\n  }\n\n  // The element's own shadow root is managed by its Lit update lifecycle.\n  // Hydrate it explicitly and bypass the support flag so the first update does\n  // not adopt the same container a second time.\n  if (\n    root.nodeType === DOCUMENT_FRAGMENT_NODE &&\n    'host' in root &&\n    root.host === element\n  ) {\n    const shadow = root as ShadowRoot;\n    const livePart = (shadow as ShadowRoot & { _$litPart$?: LitPartLike })._$litPart$;\n    if (livePart === undefined) {\n      Object.defineProperty(element, 'createRenderRoot', {\n        configurable: true,\n        value: () => shadow,\n      });\n      if (hasLitPartMarker(shadow)) {\n        const rendered = (element as unknown as { render(): unknown }).render();\n        hydrate(rendered, shadow);\n      } else {\n        shadow.replaceChildren();\n      }\n    } else if (hasLitPartMarker(shadow) && !isServerRootPart(livePart)) {\n      adoptServerShadow(element, shadow);\n      return;\n    }\n    // Support uses `_$needsHydration` in development and a minified field in\n    // production. Clearing both is harmless when support is absent.\n    (element as unknown as { _$needsHydration?: boolean })._$needsHydration = false;\n    (element as unknown as { _$AG?: boolean })._$AG = false;\n    element.requestUpdate();\n    return;\n  }\n\n  if (hasLitPartMarker(root)) {\n    const livePart = (root as ShadowRoot & { _$litPart$?: unknown })._$litPart$;\n    if (livePart !== undefined) {\n      element.requestUpdate();\n      return;\n    }\n    const rendered = (element as unknown as { render(): unknown }).render();\n    hydrate(rendered, root);\n    return;\n  }\n\n  if (root !== element && !element.isConnected) {\n    root.append(element);\n  }\n  element.requestUpdate();\n}\n"],"mappings":"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"}

package/dist/hydrate.d.cts

@@ -0,0 +1,18 @@
+import "@lit-labs/ssr-client/lit-element-hydrate-support.js";
+import { LitElement } from "lit";
+/**
+ * Hydrates server-produced markup on the client.
+ *
+ * Supported modes:
+ * 1. `root` is an element's own shadow root (or contains the Lit template
+ *    markers produced by `renderLitTemplate`): the element's current template is
+ *    hydrated into that root, preserving existing DOM and attaching event parts.
+ * 2. `root` contains a server-rendered custom element host for the same tag:
+ *    the host is upgraded so its controllers and attributes connect.
+ * 3. `root` is empty: the element is mounted and rendered normally.
+ *
+ * The function never reads a global `document`; it operates only on the supplied
+ * root and element.
+ */
+export declare function hydrateLit(root: Element | ShadowRoot, element: LitElement): void;
+//# sourceMappingURL=hydrate.d.cts.map

package/dist/hydrate.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydrate.d.cts","names":[],"sources":["../src/hydrate.ts"],"mappings":";;;;;;;;;;;;;;;;wBAsRgB,WAAW,MAAM,UAAU,YAAY,SAAS"}