@zeus-js/runtime-dom 0.1.0-beta.2 → 0.1.0-beta.4

package/dist/runtime-dom.cjs.prod.js

@@ -1,5 +1,5 @@
 /**
-* runtime-dom v0.1.0-beta.2
+* runtime-dom v0.1.0-beta.4
 * (c) 2026 baicie
 * Released under the MIT License.
 **/
@@ -166,7 +166,7 @@ function useContext(context, fallback) {
 const ZEUS_CONTEXT_REQUEST = "zeus:context-request";
 /**
 * Creates a transparent DOM element that acts as a context boundary.
-* Native custom elements inside it can use `requestDOMContext` to receive
+* Native custom elements inside it can use `resolveDOMContext` to receive
 * context values via the DOM event protocol.
 */
 function createDOMContextBoundary(context, value, children) {
@@ -178,7 +178,7 @@ function createDOMContextBoundary(context, value, children) {
 }
 /**
 * Registers a context value on a DOM target so that any descendant custom
-* element can pick it up via `requestDOMContext`.
+* element can pick it up via `resolveDOMContext`.
 */
 function provideDOMContext(target, context, value) {
 	const handler = (event) => {
@@ -196,7 +196,7 @@ function provideDOMContext(target, context, value) {
 /**
 * Internal precise DOM context resolver.
 *
-* Unlike requestDOMContext(), this can distinguish:
+* The result distinguishes:
 * - found: false, value: undefined
 * - found: true, value: undefined
 */
@@ -225,16 +225,6 @@ function resolveDOMContext(host, context) {
 		value
 	};
 }
-/**
-* Public compatibility API.
-*
-* Returns the resolved value if found, otherwise undefined.
-* If you need to distinguish "not found" from "found undefined",
-* use resolveDOMContext().
-*/
-function requestDOMContext(host, context) {
-	return resolveDOMContext(host, context).value;
-}
 function resolveValue$3(value) {
 	return typeof value === "function" ? value() : value !== null && value !== void 0 ? value : null;
 }
@@ -625,6 +615,41 @@ function mountFor(parent, marker, each, key, render) {
 }
 //#endregion
 //#region packages/core/runtime-dom/src/defineElement.ts
+const ZEUS_ELEMENT_DEFINITION = Symbol.for("zeus.element.definition");
+function prop(input, options = {}) {
+	var _options$reflect, _options$default;
+	if (Array.isArray(input)) return {
+		type: String,
+		values: input,
+		attr: options.attr,
+		reflect: options.reflect,
+		default: options.default,
+		serialize: options.serialize,
+		deserialize: options.deserialize
+	};
+	const type = input;
+	return {
+		type,
+		attr: options.attr,
+		reflect: type === Boolean ? (_options$reflect = options.reflect) !== null && _options$reflect !== void 0 ? _options$reflect : true : options.reflect,
+		default: type === Boolean ? (_options$default = options.default) !== null && _options$default !== void 0 ? _options$default : false : options.default,
+		serialize: options.serialize,
+		deserialize: options.deserialize
+	};
+}
+function event(input) {
+	if (typeof input === "string") return {
+		__zeusEvent: true,
+		name: input
+	};
+	return {
+		__zeusEvent: true,
+		name: input === null || input === void 0 ? void 0 : input.name,
+		bubbles: input === null || input === void 0 ? void 0 : input.bubbles,
+		composed: input === null || input === void 0 ? void 0 : input.composed,
+		cancelable: input === null || input === void 0 ? void 0 : input.cancelable
+	};
+}
 function createPropStore(defs) {
 	const slots = /* @__PURE__ */ new Map();
 	const props = {};
@@ -661,6 +686,12 @@ function createPropStore(defs) {
 function defineElement(tagName, options, setup) {
 	var _options$props;
 	const propDefs = normalizePropDefinitions((_options$props = options.props) !== null && _options$props !== void 0 ? _options$props : {});
+	const definition = {
+		tagName,
+		options,
+		setup,
+		propDefs
+	};
 	const observedAttributes = propDefs.filter((def) => def.attr !== false).map((def) => def.attr);
 	class ZeusElement extends HTMLElement {
 		static get observedAttributes() {
@@ -675,6 +706,13 @@ function defineElement(tagName, options, setup) {
 			this.props = this.propStore.props;
 			applyPropDefaults(this.propStore, propDefs);
 			definePropAccessors(this, this.propStore, propDefs);
+			if (options.formAssociated) this.internals = attachElementInternals(this);
+			this.setupContext = {
+				host: this,
+				internals: this.internals,
+				emit: createEmitApi(this, options.emits),
+				expose: createExpose(this)
+			};
 		}
 		connectedCallback() {
 			var _options$shadow, _options$consumes;
@@ -698,19 +736,10 @@ function defineElement(tagName, options, setup) {
 				mode,
 				lightChildren: this.lightChildren
 			};
-			const setupContext = {
-				host: this,
-				emit: (name, detail, eventOptions) => {
-					return this.dispatchEvent(new CustomEvent(name, {
-						bubbles: true,
-						composed: true,
-						cancelable: true,
-						...eventOptions,
-						detail
-					}));
-				}
-			};
-			this.dispose = render(() => runWithOwner(owner, () => withHostContext(hostContext, () => setup(this.props, setupContext))), target, { owner });
+			this.dispose = render(() => runWithOwner(owner, () => withHostContext(hostContext, () => {
+				syncFormValue(this.props, this.setupContext, options.form);
+				return setup(this.props, this.setupContext);
+			})), target, { owner });
 			mountStyles(target, options.styles);
 		}
 		disconnectedCallback() {
@@ -718,6 +747,22 @@ function defineElement(tagName, options, setup) {
 			(_this$dispose = this.dispose) === null || _this$dispose === void 0 || _this$dispose.call(this);
 			this.dispose = void 0;
 		}
+		formAssociatedCallback(form) {
+			var _options$form, _options$form$associa;
+			(_options$form = options.form) === null || _options$form === void 0 || (_options$form$associa = _options$form.associated) === null || _options$form$associa === void 0 || _options$form$associa.call(_options$form, form, this.props, this.setupContext);
+		}
+		formDisabledCallback(disabled) {
+			var _options$form2, _options$form2$disabl;
+			(_options$form2 = options.form) === null || _options$form2 === void 0 || (_options$form2$disabl = _options$form2.disabled) === null || _options$form2$disabl === void 0 || _options$form2$disabl.call(_options$form2, disabled, this.props, this.setupContext);
+		}
+		formResetCallback() {
+			var _options$form3, _options$form3$reset;
+			(_options$form3 = options.form) === null || _options$form3 === void 0 || (_options$form3$reset = _options$form3.reset) === null || _options$form3$reset === void 0 || _options$form3$reset.call(_options$form3, this.props, this.setupContext);
+		}
+		formStateRestoreCallback(state, mode) {
+			var _options$form4, _options$form4$stateR;
+			(_options$form4 = options.form) === null || _options$form4 === void 0 || (_options$form4$stateR = _options$form4.stateRestore) === null || _options$form4$stateR === void 0 || _options$form4$stateR.call(_options$form4, state, mode, this.props, this.setupContext);
+		}
 		attributeChangedCallback(name, oldValue, newValue) {
 			if (oldValue === newValue || this.reflecting) return;
 			const def = propDefs.find((item) => item.attr === name);
@@ -753,24 +798,131 @@ function defineElement(tagName, options, setup) {
 			}
 		}
 	}
+	ZeusElement.formAssociated = Boolean(options.formAssociated);
 	if (!customElements.get(tagName)) customElements.define(tagName, ZeusElement);
+	Object.defineProperty(ZeusElement, ZEUS_ELEMENT_DEFINITION, {
+		value: definition,
+		configurable: false
+	});
 	return ZeusElement;
 }
+function getElementDefinition(ctor) {
+	const definition = ctor[ZEUS_ELEMENT_DEFINITION];
+	if (!definition) throw new Error("[zeus] Element definition metadata not found.");
+	return definition;
+}
+function mountElementDefinition(ctor, host, initialValues = /* @__PURE__ */ new Map(), mountState = {}) {
+	var _options$shadow2, _mountState$lightChil, _options$consumes2, _mountState$target, _mountState$internals;
+	const { options, setup, propDefs } = getElementDefinition(ctor);
+	const propStore = createPropStore(propDefs);
+	applyPropDefaults(propStore, propDefs);
+	for (const def of propDefs) {
+		var _mountState$attribute;
+		if (def.attr !== false && ((_mountState$attribute = mountState.attributeProps) === null || _mountState$attribute === void 0 ? void 0 : _mountState$attribute.has(def.key))) {
+			propStore.set(def.key, castAttributeValue(host.getAttribute(def.attr), def));
+			initialValues.set(def.key, propStore.get(def.key));
+			continue;
+		}
+		if (initialValues.has(def.key)) {
+			propStore.set(def.key, initialValues.get(def.key));
+			continue;
+		}
+		/**
+		* Sync real definition defaults (e.g. factory defaults like `default: () => []`)
+		* back to the lazy host value map so that `element.propName` returns the
+		* correct default value rather than undefined.
+		*/
+		initialValues.set(def.key, propStore.get(def.key));
+	}
+	for (const def of propDefs) {
+		var _mountState$attribute2;
+		if (def.reflect && def.serialize && !((_mountState$attribute2 = mountState.attributeProps) === null || _mountState$attribute2 === void 0 ? void 0 : _mountState$attribute2.has(def.key))) reflectExternalProp(host, def, propStore.get(def.key), mountState.reflectingAttrs);
+	}
+	const shadow = (_options$shadow2 = options.shadow) !== null && _options$shadow2 !== void 0 ? _options$shadow2 : false;
+	const mode = shadow ? "shadow" : "light";
+	if (mode === "light" && !mountState.capturedLightChildren) {
+		mountState.lightChildren = Array.from(host.childNodes);
+		mountState.capturedLightChildren = true;
+	}
+	const lightChildren = (_mountState$lightChil = mountState.lightChildren) !== null && _mountState$lightChil !== void 0 ? _mountState$lightChil : [];
+	const owner = createOwner();
+	for (const context of (_options$consumes2 = options.consumes) !== null && _options$consumes2 !== void 0 ? _options$consumes2 : []) {
+		const resolved = resolveDOMContext(host, context);
+		if (resolved.found) owner.provides.set(context.id, resolved.value);
+		else if (context.hasDefaultValue) owner.provides.set(context.id, context.defaultValue);
+	}
+	const target = (_mountState$target = mountState.target) !== null && _mountState$target !== void 0 ? _mountState$target : mountState.target = resolveExternalRenderTarget(host, shadow);
+	const hostContext = {
+		host,
+		mode,
+		lightChildren
+	};
+	const setupContext = {
+		host,
+		internals: (_mountState$internals = mountState.internals) !== null && _mountState$internals !== void 0 ? _mountState$internals : options.formAssociated ? attachElementInternals(host) : void 0,
+		emit: createEmitApi(host, options.emits),
+		expose: createExpose(host)
+	};
+	mountState.internals = setupContext.internals;
+	const dispose = render(() => runWithOwner(owner, () => withHostContext(hostContext, () => {
+		syncFormValue(propStore.props, setupContext, options.form);
+		return setup(propStore.props, setupContext);
+	})), target, { owner });
+	mountStyles(target, options.styles);
+	return {
+		propertyChanged(name, _oldValue, newValue) {
+			var _mountState$attribute3;
+			const def = propDefs.find((item) => item.key === name);
+			const fromAttribute = Boolean((def === null || def === void 0 ? void 0 : def.attr) !== false && ((_mountState$attribute3 = mountState.attributeProps) === null || _mountState$attribute3 === void 0 ? void 0 : _mountState$attribute3.has(name)));
+			const value = fromAttribute && def ? castAttributeValue(typeof newValue === "string" ? newValue : null, def) : newValue;
+			propStore.set(name, value);
+			initialValues.set(name, value);
+			if ((def === null || def === void 0 ? void 0 : def.reflect) && !fromAttribute) reflectExternalProp(host, def, value, mountState.reflectingAttrs);
+		},
+		formAssociated(form) {
+			var _options$form5, _options$form5$associ;
+			(_options$form5 = options.form) === null || _options$form5 === void 0 || (_options$form5$associ = _options$form5.associated) === null || _options$form5$associ === void 0 || _options$form5$associ.call(_options$form5, form, propStore.props, setupContext);
+		},
+		formDisabled(disabled) {
+			var _options$form6, _options$form6$disabl;
+			(_options$form6 = options.form) === null || _options$form6 === void 0 || (_options$form6$disabl = _options$form6.disabled) === null || _options$form6$disabl === void 0 || _options$form6$disabl.call(_options$form6, disabled, propStore.props, setupContext);
+		},
+		formReset() {
+			var _options$form7, _options$form7$reset;
+			(_options$form7 = options.form) === null || _options$form7 === void 0 || (_options$form7$reset = _options$form7.reset) === null || _options$form7$reset === void 0 || _options$form7$reset.call(_options$form7, propStore.props, setupContext);
+		},
+		formStateRestore(state, mode) {
+			var _options$form8, _options$form8$stateR;
+			(_options$form8 = options.form) === null || _options$form8 === void 0 || (_options$form8$stateR = _options$form8.stateRestore) === null || _options$form8$stateR === void 0 || _options$form8$stateR.call(_options$form8, state, mode, propStore.props, setupContext);
+		},
+		dispose() {
+			dispose();
+		}
+	};
+}
 function normalizePropDefinitions(props) {
 	return Object.keys(props).map((key) => {
+		const propKey = String(key);
 		const input = props[key];
-		if (typeof input === "function") return {
-			key,
-			attr: toKebabCase(key),
-			type: input,
-			reflect: false
-		};
+		if (typeof input === "function") {
+			const type = input;
+			return {
+				key: propKey,
+				attr: isAttributeBackedConstructor(type) ? toKebabCase(propKey) : false,
+				type,
+				reflect: false
+			};
+		}
+		const type = input === null || input === void 0 ? void 0 : input.type;
+		const defaultAttr = isAttributeBackedConstructor(type) ? toKebabCase(propKey) : false;
 		return {
-			key,
-			attr: (input === null || input === void 0 ? void 0 : input.attr) === void 0 ? toKebabCase(key) : input.attr,
-			type: input === null || input === void 0 ? void 0 : input.type,
+			key: propKey,
+			attr: (input === null || input === void 0 ? void 0 : input.attr) === void 0 ? defaultAttr : input.attr,
+			type,
 			reflect: Boolean(input === null || input === void 0 ? void 0 : input.reflect),
-			default: input === null || input === void 0 ? void 0 : input.default
+			default: input === null || input === void 0 ? void 0 : input.default,
+			serialize: input === null || input === void 0 ? void 0 : input.serialize,
+			deserialize: input === null || input === void 0 ? void 0 : input.deserialize
 		};
 	});
 }
@@ -803,6 +955,7 @@ function definePropAccessors(element, store, defs) {
 	}
 }
 function castAttributeValue(value, def) {
+	if (def.deserialize) return def.deserialize(value);
 	if (def.type === Boolean) return value !== null;
 	if (value === null) return;
 	if (def.type === Number) return Number(value);
@@ -811,10 +964,17 @@ function castAttributeValue(value, def) {
 	} catch {
 		return def.type === Array ? [] : {};
 	}
+	if (def.type === Function) return;
 	return value;
 }
 function reflectPropToAttribute(element, def, value) {
 	if (def.attr === false) return;
+	if (def.serialize) {
+		const serialized = def.serialize(value);
+		if (serialized == null) element.removeAttribute(def.attr);
+		else element.setAttribute(def.attr, serialized);
+		return;
+	}
 	if (def.type === Boolean) {
 		if (value) element.setAttribute(def.attr, "");
 		else element.removeAttribute(def.attr);
@@ -828,8 +988,84 @@ function reflectPropToAttribute(element, def, value) {
 		element.setAttribute(def.attr, JSON.stringify(value));
 		return;
 	}
+	if (def.type === Function) return;
 	element.setAttribute(def.attr, String(value));
 }
+function reflectExternalProp(element, def, value, reflectingAttrs) {
+	if (def.attr === false) return;
+	const attrName = def.attr.toLowerCase();
+	reflectingAttrs === null || reflectingAttrs === void 0 || reflectingAttrs.add(attrName);
+	try {
+		reflectPropToAttribute(element, def, value);
+	} finally {
+		reflectingAttrs === null || reflectingAttrs === void 0 || reflectingAttrs.delete(attrName);
+	}
+}
+function syncFormValue(props, context, form) {
+	const valueResolver = form === null || form === void 0 ? void 0 : form.value;
+	const stateResolver = form === null || form === void 0 ? void 0 : form.state;
+	if (!context.internals || valueResolver === void 0) return;
+	(0, _zeus_js_signal.effect)(() => {
+		const value = resolveFormValue(props, valueResolver);
+		const state = stateResolver === void 0 ? void 0 : resolveFormValue(props, stateResolver);
+		context.internals.setFormValue(value, state);
+	});
+}
+function resolveFormValue(props, resolver) {
+	if (typeof resolver === "function") {
+		var _resolver;
+		return (_resolver = resolver(props)) !== null && _resolver !== void 0 ? _resolver : null;
+	}
+	const value = props[resolver];
+	return value == null ? null : value;
+}
+function attachElementInternals(host) {
+	const attachInternals = host.attachInternals;
+	if (typeof attachInternals !== "function") return;
+	try {
+		return attachInternals.call(host);
+	} catch (error) {
+		return;
+	}
+}
+function createEmitApi(host, emits) {
+	const emit = {};
+	const dispatch = (name, detail, options) => {
+		var _definition$name, _ref, _options$bubbles, _ref2, _options$composed, _ref3, _options$cancelable;
+		const definition = emits === null || emits === void 0 ? void 0 : emits[name];
+		return host.dispatchEvent(new CustomEvent((_definition$name = definition === null || definition === void 0 ? void 0 : definition.name) !== null && _definition$name !== void 0 ? _definition$name : toKebabCase(name), {
+			bubbles: (_ref = (_options$bubbles = options === null || options === void 0 ? void 0 : options.bubbles) !== null && _options$bubbles !== void 0 ? _options$bubbles : definition === null || definition === void 0 ? void 0 : definition.bubbles) !== null && _ref !== void 0 ? _ref : true,
+			composed: (_ref2 = (_options$composed = options === null || options === void 0 ? void 0 : options.composed) !== null && _options$composed !== void 0 ? _options$composed : definition === null || definition === void 0 ? void 0 : definition.composed) !== null && _ref2 !== void 0 ? _ref2 : true,
+			cancelable: (_ref3 = (_options$cancelable = options === null || options === void 0 ? void 0 : options.cancelable) !== null && _options$cancelable !== void 0 ? _options$cancelable : definition === null || definition === void 0 ? void 0 : definition.cancelable) !== null && _ref3 !== void 0 ? _ref3 : false,
+			detail
+		}));
+	};
+	if (emits) for (const key of Object.keys(emits)) Object.defineProperty(emit, key, {
+		configurable: true,
+		enumerable: true,
+		value(detail, options) {
+			return dispatch(key, detail, options);
+		}
+	});
+	return emit;
+}
+function createExpose(host) {
+	return (methods) => {
+		for (const key of Object.keys(methods)) Object.defineProperty(host, key, {
+			configurable: true,
+			enumerable: false,
+			value: methods[key]
+		});
+	};
+}
+function isAttributeBackedConstructor(type) {
+	return type === String || type === Number || type === Boolean;
+}
+function resolveExternalRenderTarget(host, shadow) {
+	var _host$shadowRoot;
+	if (!shadow) return host;
+	return (_host$shadowRoot = host.shadowRoot) !== null && _host$shadowRoot !== void 0 ? _host$shadowRoot : host.attachShadow(typeof shadow === "object" ? shadow : { mode: "open" });
+}
 function mountStyles(target, styles) {
 	if (!styles) return;
 	const list = Array.isArray(styles) ? styles : [styles];
@@ -971,6 +1207,7 @@ exports.Host = Host;
 exports.Show = Show;
 exports.Slot = Slot;
 exports.ZEUS_CONTEXT_REQUEST = ZEUS_CONTEXT_REQUEST;
+exports.ZEUS_ELEMENT_DEFINITION = ZEUS_ELEMENT_DEFINITION;
 exports.bindAttr = bindAttr;
 exports.bindClass = bindClass;
 exports.bindEvent = bindEvent;
@@ -988,21 +1225,24 @@ exports.createOwner = createOwner;
 exports.createSlot = createSlot;
 exports.defineElement = defineElement;
 exports.delegateEvents = delegateEvents;
+exports.event = event;
 exports.getCurrentHostContext = getCurrentHostContext;
 exports.getCurrentOwner = getCurrentOwner;
+exports.getElementDefinition = getElementDefinition;
 exports.inject = inject;
 exports.insert = insert;
 exports.insertTracked = insertTracked;
 exports.marker = marker;
 exports.mountDynamic = mountDynamic;
+exports.mountElementDefinition = mountElementDefinition;
 exports.mountFor = mountFor;
 exports.mountShow = mountShow;
 exports.normalizeClass = normalizeClass;
+exports.prop = prop;
 exports.provide = provide;
 exports.provideDOMContext = provideDOMContext;
 exports.removeNodes = removeNodes;
 exports.render = render;
-exports.requestDOMContext = requestDOMContext;
 exports.resolveDOMContext = resolveDOMContext;
 exports.resolveValue = resolveValue;
 exports.runWithOwner = runWithOwner;

package/dist/runtime-dom.d.ts

@@ -72,31 +72,23 @@ export interface DOMContextResolution<T> {
 }
 /**
  * Creates a transparent DOM element that acts as a context boundary.
- * Native custom elements inside it can use `requestDOMContext` to receive
+ * Native custom elements inside it can use `resolveDOMContext` to receive
  * context values via the DOM event protocol.
  */
 export declare function createDOMContextBoundary<T>(context: Context<T>, value: T, children: JSXValue): Element;
 /**
  * Registers a context value on a DOM target so that any descendant custom
- * element can pick it up via `requestDOMContext`.
+ * element can pick it up via `resolveDOMContext`.
  */
 export declare function provideDOMContext<T>(target: EventTarget, context: Context<T>, value: T): void;
 /**
  * Internal precise DOM context resolver.
  *
- * Unlike requestDOMContext(), this can distinguish:
+ * The result distinguishes:
  * - found: false, value: undefined
  * - found: true, value: undefined
  */
 export declare function resolveDOMContext<T>(host: HTMLElement, context: Context<T>): DOMContextResolution<T>;
-/**
- * Public compatibility API.
- *
- * Returns the resolved value if found, otherwise undefined.
- * If you need to distinguish "not found" from "found undefined",
- * use resolveDOMContext().
- */
-export declare function requestDOMContext<T>(host: HTMLElement, context: Context<T>): T | undefined;
 
 export interface RenderOptions {
     owner?: ReturnType<typeof createOwner>;
@@ -145,15 +137,57 @@ export type ForProps<T, K = unknown> = {
 export declare function For<T, K = unknown>(props: ForProps<T, K>): JSXValue;
 export declare function mountFor<T, K = unknown>(parent: Node, marker: Node, each: () => readonly T[] | null | undefined, key: ((item: T, index: number) => K) | undefined, render: (item: T, index: number) => JSXValue): void;
 
-export type ElementPropConstructor = StringConstructor | NumberConstructor | BooleanConstructor | ObjectConstructor | ArrayConstructor;
-export type PropDefinition<T = unknown> = ElementPropConstructor | {
+export type ElementPropConstructor = StringConstructor | NumberConstructor | BooleanConstructor | ObjectConstructor | ArrayConstructor | FunctionConstructor;
+export type PropSerializer<T = unknown> = {
+    bivarianceHack(value: T | undefined): string | null | undefined;
+}['bivarianceHack'];
+export type PropDeserializer<T = unknown> = {
+    bivarianceHack(value: string | null): T | undefined;
+}['bivarianceHack'];
+export interface PropDefinitionOptions<T = unknown> {
     type?: ElementPropConstructor;
     attr?: string | false;
     reflect?: boolean;
     default?: T | (() => T);
+    values?: readonly T[];
+    serialize?(value: T | undefined): string | null | undefined;
+    deserialize?(value: string | null): T | undefined;
+}
+export type PropDefinition<T = unknown> = ElementPropConstructor | PropDefinitionOptions<T>;
+export interface ValuePropDefinition<T = unknown> extends PropDefinitionOptions<T> {
+    type: StringConstructor;
+    values: readonly T[];
+}
+type ConstructorPropDefinition<T = unknown, C extends ElementPropConstructor = ElementPropConstructor> = PropDefinitionOptions<T> & {
+    type: C;
+};
+export interface EventDefinition<Detail = unknown> {
+    __zeusEvent: true;
+    name?: string;
+    bubbles?: boolean;
+    composed?: boolean;
+    cancelable?: boolean;
+    __detail?: Detail;
+}
+export interface EventOptions {
+    name?: string;
+    bubbles?: boolean;
+    composed?: boolean;
+    cancelable?: boolean;
+}
+export interface EmitsOptions {
+    [key: string]: EventDefinition<unknown>;
+}
+export type FormAssociatedValue = File | FormData | string | null;
+export type FormStateRestoreMode = 'restore' | 'autocomplete';
+type ExplicitPropKeys<T> = keyof {
+    [K in keyof T as string extends K ? never : number extends K ? never : symbol extends K ? never : K]: T[K];
+};
+export type EmitApi<E extends EmitsOptions> = {
+    [K in keyof E]: E[K] extends EventDefinition<infer Detail> ? (detail: Detail, options?: CustomEventInit) => boolean : never;
 };
 export type PropOptions<P extends object> = Partial<{
-    [K in keyof P]: PropDefinition<P[K]>;
+    [K in ExplicitPropKeys<P>]: PropDefinition<P[K]>;
 }>;
 export interface DefineElementMeta {
     description?: string;
@@ -169,27 +203,101 @@ export interface DefineElementMeta {
     slots?: Record<string, {
         description?: string;
     }>;
-    cssVars?: string[];
+    cssVars?: Record<string, {
+        description?: string;
+    }>;
     cssParts?: string[];
     [key: string]: unknown;
 }
-export interface DefineElementOptions<P extends object> {
+export interface DefineElementOptions<P extends object, E extends EmitsOptions = EmitsOptions> {
     shadow?: boolean | ShadowRootInit;
+    formAssociated?: boolean;
+    form?: FormAssociatedOptions<P, HTMLElement, E>;
     props?: PropOptions<P>;
+    emits?: E;
     styles?: string | string[];
     consumes?: Context<any>[];
+    models?: readonly ElementModelDefinition<P>[];
+    slots?: readonly string[];
+    parts?: readonly string[];
+    cssVars?: Record<string, {
+        description?: string;
+    }>;
     /**
      * Metadata only.
      * Runtime does not consume this field.
      */
     meta?: DefineElementMeta;
 }
-export interface DefineElementContext<E extends HTMLElement = HTMLElement> {
+export interface FormAssociatedOptions<P extends object, E extends HTMLElement = HTMLElement, Emits extends EmitsOptions = EmitsOptions> {
+    value?: ExplicitPropKeys<P> | ((props: Readonly<P>) => FormAssociatedValue);
+    state?: ExplicitPropKeys<P> | ((props: Readonly<P>) => FormAssociatedValue);
+    associated?(form: HTMLFormElement | null, props: Readonly<P>, context: DefineElementContext<E, Emits>): void;
+    disabled?(disabled: boolean, props: Readonly<P>, context: DefineElementContext<E, Emits>): void;
+    reset?(props: Readonly<P>, context: DefineElementContext<E, Emits>): void;
+    stateRestore?(state: FormAssociatedValue, mode: FormStateRestoreMode, props: Readonly<P>, context: DefineElementContext<E, Emits>): void;
+}
+export interface ElementModelDefinition<P extends object> {
+    prop: ExplicitPropKeys<P>;
+    event: string;
+    eventPath?: string;
+}
+export interface DefineElementContext<E extends HTMLElement = HTMLElement, Emits extends EmitsOptions = EmitsOptions> {
     host: E;
-    emit: (name: string, detail?: unknown, options?: CustomEventInit) => boolean;
+    internals?: ElementInternals;
+    emit: EmitApi<Emits>;
+    expose(methods: Record<string, Function>): void;
+}
+export type DefineElementSetup<P extends object, E extends HTMLElement = HTMLElement, Emits extends EmitsOptions = EmitsOptions> = (props: Readonly<P>, context: DefineElementContext<E, Emits>) => JSXValue;
+export type NormalizedPropDefinition = {
+    key: string;
+    attr: string | false;
+    type?: ElementPropConstructor;
+    reflect: boolean;
+    default?: unknown;
+    serialize?: (value: unknown) => string | null | undefined;
+    deserialize?: (value: string | null) => unknown;
+};
+export declare const ZEUS_ELEMENT_DEFINITION: unique symbol;
+export interface ZeusElementDefinition<P extends object = object, E extends HTMLElement = HTMLElement, Emits extends EmitsOptions = EmitsOptions> {
+    tagName: string;
+    options: DefineElementOptions<P, Emits>;
+    setup: DefineElementSetup<P, E, Emits>;
+    propDefs: NormalizedPropDefinition[];
+}
+export type ZeusElementConstructor = CustomElementConstructor & {
+    [ZEUS_ELEMENT_DEFINITION]?: ZeusElementDefinition;
+};
+export interface MountedElementDefinition {
+    propertyChanged(name: string, _oldValue: unknown, newValue: unknown): void;
+    formAssociated(form: HTMLFormElement | null): void;
+    formDisabled(disabled: boolean): void;
+    formReset(): void;
+    formStateRestore(state: FormAssociatedValue, mode: FormStateRestoreMode): void;
+    dispose(): void;
+}
+export declare function prop<const V extends readonly string[]>(values: V, options?: Omit<PropDefinitionOptions<V[number]>, 'type' | 'values'>): ValuePropDefinition<V[number]>;
+export declare function prop(type: BooleanConstructor, options?: Omit<PropDefinitionOptions<boolean>, 'type' | 'values'>): ConstructorPropDefinition<boolean, BooleanConstructor>;
+export declare function prop<T = unknown>(type: Exclude<ElementPropConstructor, BooleanConstructor>, options?: Omit<PropDefinitionOptions<T>, 'type' | 'values'>): ConstructorPropDefinition<T>;
+export declare function event<Detail = unknown>(): EventDefinition<Detail>;
+export declare function event<Detail = unknown>(name: string): EventDefinition<Detail>;
+export declare function event<Detail = unknown>(options: EventOptions): EventDefinition<Detail>;
+/**
+ * Persisted mount state for a lazy-loaded element.
+ * Used across disconnect/reconnect cycles to avoid re-capturing
+ * light DOM children or re-attaching shadow roots.
+ */
+export interface ElementDefinitionMountState {
+    target?: Element | ShadowRoot;
+    lightChildren?: Node[];
+    capturedLightChildren?: boolean;
+    internals?: ElementInternals;
+    attributeProps?: Set<string>;
+    reflectingAttrs?: Set<string>;
 }
-export type DefineElementSetup<P extends object, E extends HTMLElement = HTMLElement> = (props: Readonly<P>, context: DefineElementContext<E>) => JSXValue;
-export declare function defineElement<P extends object = object, E extends HTMLElement = HTMLElement>(tagName: string, options: DefineElementOptions<P>, setup: DefineElementSetup<P, E>): CustomElementConstructor;
+export declare function defineElement<P extends object = Record<string, unknown>, E extends HTMLElement = HTMLElement, Emits extends EmitsOptions = EmitsOptions>(tagName: string, options: DefineElementOptions<P, Emits>, setup: DefineElementSetup<P, E, Emits>): CustomElementConstructor;
+export declare function getElementDefinition(ctor: CustomElementConstructor): ZeusElementDefinition;
+export declare function mountElementDefinition(ctor: CustomElementConstructor, host: HTMLElement, initialValues?: Map<string, unknown>, mountState?: ElementDefinitionMountState): MountedElementDefinition;
 
 type HostValue<T> = T | (() => T);
 export interface HostProps extends Record<string, unknown> {