@solidjs/web 2.0.0-beta.2 → 2.0.0-beta.21

package/types/server.d.ts

@@ -1,21 +1,70 @@
 import { JSX } from "./jsx.js";
-export const Properties: Set<string>;
+import { SerializerPlugin } from "./serializer.js";
+export const DOMWithState: Record<string, Record<string, 1 | 2>>;
 export const ChildProperties: Set<string>;
 export const DelegatedEvents: Set<string>;
 export const DOMElements: Set<string>;
 export const SVGElements: Set<string>;
-export const SVGNamespace: Record<string, string>;
+export const MathMLElements: Set<string>;
+export const VoidElements: Set<string>;
+export const RawTextElements: Set<string>;
+export const Namespaces: Record<string, string>;
 
 type MountableElement = Element | Document | ShadowRoot | DocumentFragment | Node;
 
+/** Static asset manifest produced by a build (e.g. parsed Vite manifest.json). */
+export type AssetManifest = Record<
+  string,
+  { file: string; css?: string[]; isEntry?: boolean; imports?: string[] }
+> & { _base?: string };
+
+/** Inline style content, e.g. dev CSS collected from a bundler's module graph. */
+export type InlineStyleAsset = {
+  id: string;
+  content: string;
+  attrs?: Record<string, string>;
+};
+
+export type ResolvedAssets = {
+  js: string[];
+  css: (string | InlineStyleAsset)[];
+};
+
+/**
+ * Resolver form of the manifest option — the primitive a dev server
+ * implements against its live module graph (a static manifest object is
+ * normalized into a sync resolver internally). `resolve` may return a
+ * promise (async resolvers require streaming rendering); CSS entries may be
+ * URL strings (emitted as load-gated `<link>` tags) or inline-style
+ * descriptors (emitted as `<style>` tags). A bare `resolve`-shaped function
+ * is accepted as shorthand for `{ resolve }`.
+ */
+export type AssetResolver = {
+  resolve(
+    key: string
+  ): ResolvedAssets | null | undefined | Promise<ResolvedAssets | null | undefined>;
+  /**
+   * Synchronous fast path answering with whatever is knowable without async
+   * work (typically js URLs, omitting css). Sync consumers — e.g. a lazy
+   * component's `moduleUrl` getter used by islands — use this when `resolve`
+   * would return a promise, so adapters should provide it whenever possible.
+   */
+  resolveSync?(key: string): ResolvedAssets | null | undefined;
+};
+
+/** Bare-function shorthand for `AssetResolver` (no sync fast path). */
+export type AssetResolverFn = (
+  key: string
+) => ResolvedAssets | null | undefined | Promise<ResolvedAssets | null | undefined>;
+
 export function renderToString<T>(
   fn: () => T,
   options?: {
     nonce?: string;
     renderId?: string;
     noScripts?: boolean;
-    plugins?: any[];
-    manifest?: Record<string, { file: string; css?: string[]; isEntry?: boolean; imports?: string[] }> & { _base?: string };
+    plugins?: SerializerPlugin[];
+    manifest?: AssetManifest | AssetResolver | AssetResolverFn;
     onError?: (err: any) => void;
   }
 ): string;
@@ -27,8 +76,8 @@ export function renderToStringAsync<T>(
     nonce?: string;
     renderId?: string;
     noScripts?: boolean;
-    plugins?: any[];
-    manifest?: Record<string, { file: string; css?: string[]; isEntry?: boolean; imports?: string[] }> & { _base?: string };
+    plugins?: SerializerPlugin[];
+    manifest?: AssetManifest | AssetResolver | AssetResolverFn;
     onError?: (err: any) => void;
   }
 ): Promise<string>;
@@ -38,8 +87,8 @@ export function renderToStream<T>(
     nonce?: string;
     renderId?: string;
     noScripts?: boolean;
-    plugins?: any[];
-    manifest?: Record<string, { file: string; css?: string[]; isEntry?: boolean; imports?: string[] }> & { _base?: string };
+    plugins?: SerializerPlugin[];
+    manifest?: AssetManifest | AssetResolver | AssetResolverFn;
     onCompleteShell?: (info: { write: (v: string) => void }) => void;
     onCompleteAll?: (info: { write: (v: string) => void }) => void;
     onError?: (err: any) => void;
@@ -62,25 +111,50 @@ export function ssrClassName(value: string | { [k: string]: boolean } | Array<an
 export function ssrStyle(value: string | { [k: string]: string }): string;
 export function ssrStyleProperty(name: string, value: any): string;
 export function ssrAttribute(key: string, value: any): string;
+export function ssrGroup<T extends () => any[]>(fn: T, n: number): T;
+export function scope<T>(fn: () => T): () => unknown;
 export function ssrHydrationKey(): string;
 export function resolveSSRNode(node: any, result?: any, top?: boolean): any;
 export function escape(s: any, attr?: boolean): any;
-export function applyRef(r: ((element: any) => void) | ((element: any) => void)[], element: any): void;
+export function applyRef(
+  r: ((element: any) => void) | ((element: any) => void)[],
+  element: any
+): void;
 export function useAssets(fn: () => JSX.Element): void;
 export function getAssets(): string;
 export function getHydrationKey(): string | undefined;
-export function effect<T>(fn: (prev?: T) => T, effect: (value: T, prev?: T) => void, init?: T): void;
+export function effect<T>(fn: (prev?: T) => T, effect: (value: T, prev?: T) => void): void;
 export function memo<T>(fn: () => T, equal: boolean): () => T;
 export function createComponent<T>(Comp: (props: T) => JSX.Element, props: T): JSX.Element;
 export function mergeProps(...sources: unknown[]): unknown;
 export function getOwner(): unknown;
-export function ssrRunInScope(fn: () => void, owner: unknown): void;
-export function generateHydrationScript(options?: { nonce?: string; eventNames?: string[] }): string;
+export function generateHydrationScript(options?: {
+  nonce?: string;
+  eventNames?: string[];
+}): string;
+/**
+ * Registered symbol (`Symbol.for("solid.RequestContext")`) naming the
+ * global slot where `provideRequestEvent` parks the AsyncLocalStorage that
+ * scopes request events. Integration plumbing — application code reads the
+ * event through `getRequestEvent()` instead.
+ * @internal
+ */
 export declare const RequestContext: unique symbol;
+/**
+ * The per-request context available on the server: the incoming `Request`
+ * and a `locals` bag integrations and middleware can hang state on.
+ * Frameworks typically extend this shape with richer fields.
+ */
 export interface RequestEvent {
   request: Request;
   locals: Record<string | number | symbol, any>;
 }
+/**
+ * The current request event, when called on the server inside a request
+ * scope (established by `provideRequestEvent` from `@solidjs/web/storage`
+ * or by the framework). Undefined on the client and outside a request.
+ * Read it above `await` boundaries in partially-polyfilled environments.
+ */
 export function getRequestEvent(): RequestEvent | undefined;
 
 export function Assets(props: { children?: JSX.Element }): JSX.Element;
@@ -104,15 +178,26 @@ export function insert<T>(
 ): JSX.Element;
 
 /** @deprecated not supported on the server side */
-export function spread<T>(
-  node: Element,
-  accessor: T,
-  isSVG?: Boolean,
-  skipChildren?: Boolean
-): void;
+export function spread<T>(node: Element, accessor: T, skipChildren?: Boolean): void;
 
 /** @deprecated not supported on the server side */
-export function delegateEvents(eventNames: string[], d?: Document): void;
+export function delegateEvents(eventNames: string[]): void;
+/** @deprecated not supported on the server side */
+export function registerDelegatedRoot(root: MountableElement): void;
+/** @deprecated not supported on the server side */
+export function unregisterDelegatedRoot(root: MountableElement): void;
+/** @deprecated not supported on the server side */
+export function registerDelegatedContainer(
+  container: MountableElement,
+  owner?: MountableElement
+): void;
+/** @deprecated not supported on the server side */
+export function unregisterDelegatedContainer(
+  container: MountableElement,
+  owner?: MountableElement
+): void;
+/** @deprecated not supported on the server side */
+export function getDelegatedRoot(node: MountableElement): MountableElement | undefined;
 /** @deprecated not supported on the server side */
 export function dynamicProperty(props: unknown, key: string): unknown;
 /** @deprecated not supported on the server side */
@@ -121,23 +206,24 @@ export function setAttribute(node: Element, name: string, value: string): void;
 export function setAttributeNS(node: Element, namespace: string, name: string, value: string): void;
 
 /** @deprecated not supported on the server side */
-export function addEventListener(
-  node: Element,
-  name: string,
-  handler: () => void,
-  delegate: boolean
-): void;
+export function addEvent(node: Element, name: string, handler: () => void, delegate: boolean): void;
 
 /** @deprecated not supported on the server side */
 export function render(code: () => JSX.Element, element: MountableElement): () => void;
-/** @deprecated not supported on the server side */
-export function template(html: string, isImportNode?: boolean, isSVG?: boolean, isMathML?: boolean): () => Element;
+/**
+ * @deprecated not supported on the server side
+ * @param flag
+ * - `undefined` — clone the template as-is (uses `cloneNode`).
+ * - `1` — use `document.importNode` instead of `cloneNode`.
+ * - `2` — the template html is wrapped; the outer tag is stripped at clone time.
+ */
+export function template(html: string, flag?: 1 | 2): () => Element;
 /** @deprecated not supported on the server side */
 export function setProperty(node: Element, name: string, value: any): void;
 /** @deprecated not supported on the server side */
 export function className(node: Element, value: string): void;
 /** @deprecated not supported on the server side */
-export function assign(node: Element, props: any, isSVG?: Boolean, skipChildren?: Boolean): void;
+export function assign(node: Element, props: any, skipChildren?: Boolean): void;
 
 /** @deprecated not supported on the server side */
 export function hydrate(
@@ -154,3 +240,12 @@ export function getNextMatch(start: Node, elementName: string): Element;
 export function getNextMarker(start: Node): [Node, Array<Node>];
 /** @deprecated not supported on the server side */
 export function runHydrationEvents(): void;
+/** @deprecated not supported on the server side */
+export function ref(
+  fn: () => ((element: Element) => void) | ((element: Element) => void)[],
+  element: Element
+): void;
+/** @deprecated not supported on the server side */
+export function setStyleProperty(node: Element, name: string, value: any): void;
+/** @deprecated not supported on the server side — register assets through the render context instead */
+export function acquireAsset(descriptor: unknown): () => void;

package/types-cjs/client.d.cts

@@ -0,0 +1,131 @@
+import { JSX } from "./jsx.cjs";
+export const DOMWithState: Record<string, Record<string, 1 | 2>>;
+export const ChildProperties: Set<string>;
+export const DelegatedEvents: Set<string>;
+export const DOMElements: Set<string>;
+export const SVGElements: Set<string>;
+export const MathMLElements: Set<string>;
+export const VoidElements: Set<string>;
+export const RawTextElements: Set<string>;
+export const Namespaces: Record<string, string>;
+
+type MountableElement = Element | Document | ShadowRoot | DocumentFragment | Node;
+export function render(
+  code: () => JSX.Element,
+  element: MountableElement,
+  init?: JSX.Element,
+  options?: { owner?: unknown }
+): () => void;
+/**
+ * @param flag
+ * - `undefined` — clone the template as-is (uses `cloneNode`).
+ * - `1` — use `document.importNode` instead of `cloneNode`.
+ * - `2` — the template html is wrapped; the outer tag is stripped at clone time.
+ */
+export function template(html: string, flag?: 1 | 2): () => Element;
+export function scope<T extends () => any>(fn: T): T;
+export function effect<T>(fn: (prev?: T) => T, effect: (value: T, prev?: T) => void): void;
+export function memo<T>(fn: () => T, equal: boolean): () => T;
+export function untrack<T>(fn: () => T): T;
+export function insert<T>(
+  parent: MountableElement,
+  accessor: (() => T) | T,
+  marker?: Node | null,
+  init?: JSX.Element,
+  options?: {
+    /**
+     * Live accessor for the slot's logical host in the source tree (portals).
+     * Each top-level node the slot manages is tagged with a `_$host` getter
+     * backed by this accessor so delegated events retarget correctly.
+     */
+    host?: () => Node | null;
+    /** Defer the insert effect to the queue instead of running it inline. */
+    schedule?: boolean;
+  }
+): JSX.Element;
+export function createComponent<T>(Comp: (props: T) => JSX.Element, props: T): JSX.Element;
+export function delegateEvents(eventNames: string[]): void;
+export function registerDelegatedRoot(root: MountableElement): void;
+export function unregisterDelegatedRoot(root: MountableElement): void;
+export function registerDelegatedContainer(
+  container: MountableElement,
+  owner?: MountableElement
+): void;
+export function unregisterDelegatedContainer(
+  container: MountableElement,
+  owner?: MountableElement
+): void;
+export function getDelegatedRoot(node: MountableElement): MountableElement | undefined;
+export function spread<T>(node: Element, accessor: T, skipChildren?: Boolean): void;
+export function assign(
+  node: Element,
+  props: any,
+  skipChildren?: Boolean,
+  prevProps?: any,
+  skipRef?: Boolean
+): void;
+export function setAttribute(node: Element, name: string, value: string): void;
+export function setAttributeNS(node: Element, namespace: string, name: string, value: string): void;
+export function className(node: Element, value: JSX.ClassValue, prev?: JSX.ClassValue): void;
+export function setProperty(node: Element, name: string, value: any): void;
+export function setStyleProperty(node: Element, name: string, value: any): void;
+export function addEvent(
+  node: Element,
+  name: string,
+  handler: EventListener | EventListenerObject | (EventListenerObject & AddEventListenerOptions),
+  delegate: boolean
+): void;
+export function style(
+  node: Element,
+  value: { [k: string]: string },
+  prev?: { [k: string]: string }
+): void;
+export function getOwner(): unknown;
+export function mergeProps(...sources: unknown[]): unknown;
+export function dynamicProperty(props: unknown, key: string): unknown;
+export function applyRef(
+  r: ((element: Element) => void) | ((element: Element) => void)[],
+  element: Element
+): void;
+export function ref(
+  fn: () => ((element: Element) => void) | ((element: Element) => void)[],
+  element: Element
+): void;
+
+export function hydrate(
+  fn: () => JSX.Element,
+  node: MountableElement,
+  options?: { renderId?: string; owner?: unknown }
+): () => void;
+export function getHydrationKey(): string | undefined;
+export function getNextElement(template?: () => Element): Element;
+export function getNextMatch(start: Node, elementName: string): Element;
+export function getNextMarker(start: Node): [Node, Array<Node>];
+export function useAssets(fn: () => JSX.Element): void;
+export function getAssets(): string;
+export type AssetDescriptor =
+  | { type: "style"; href: string; attrs?: Record<string, string> }
+  | { type: "inline-style"; id: string; content?: string; attrs?: Record<string, string> }
+  | { type: "module"; href: string }
+  | ExclusiveAssetDescriptor<any>;
+export interface ExclusiveAssetDescriptor<T> {
+  policy: "exclusive";
+  key: string;
+  value: T;
+  get(): T;
+  set(value: T): void;
+}
+export function acquireAsset(descriptor: AssetDescriptor): () => void;
+export function HydrationScript(props?: { nonce?: string; eventNames?: string[] }): JSX.Element;
+export function generateHydrationScript(options?: {
+  nonce?: string;
+  eventNames?: string[];
+}): string;
+export function Assets(props: { children?: JSX.Element }): JSX.Element;
+export interface RequestEvent {
+  request: Request;
+  locals: Record<string | number | symbol, any>;
+}
+export declare const RequestContext: unique symbol;
+export function getRequestEvent(): RequestEvent | undefined;
+export function runHydrationEvents(): void;

package/types-cjs/core.d.cts

@@ -0,0 +1,3 @@
+export { getOwner, runWithOwner, createComponent, createRoot as root, sharedConfig, untrack, merge as mergeProps, flatten, ssrHandleError, ssrScope } from "solid-js";
+export declare const effect: (fn: any, effectFn: any, options: any) => void;
+export declare const memo: (fn: any) => import("solid-js").SourceAccessor<any>;

package/types-cjs/index.d.cts

@@ -0,0 +1,178 @@
+import { hydrate as hydrateCore } from "./client.cjs";
+import { Component } from "solid-js";
+import type { JSX } from "./jsx.cjs";
+export * from "./client.cjs";
+export * from "./server-mock.cjs";
+export * from "./response.cjs";
+export type { JSX } from "./jsx.cjs";
+export { For, Show, Switch, Match, Errored, Loading, Repeat, Reveal, NoHydration, Hydration } from "solid-js";
+import { merge } from "solid-js";
+/**
+ * Compiler-emitted prop-spread helper. The JSX transform (in
+ * `dom-expressions`) emits `mergeProps(...)` calls when compiling prop
+ * spreads on components — it is *not* a user-facing API. Application code
+ * should import `merge` from `solid-js` directly.
+ *
+ * @internal
+ */
+export declare const mergeProps: typeof merge;
+/**
+ * Build-time constant indicating whether code is running on the server. This
+ * client entry sets it to `false`; the matching server entry (`@solidjs/web`
+ * resolved through the `solid` server export condition) sets it to `true`.
+ *
+ * Bundlers can dead-code-eliminate branches gated on `isServer`, so guarding
+ * browser-only code with `if (!isServer) {…}` keeps it out of the SSR bundle
+ * entirely.
+ *
+ * @example
+ * ```ts
+ * import { isServer } from "@solidjs/web";
+ *
+ * if (!isServer) {
+ *   // Browser-only: tree-shaken out of the SSR bundle.
+ *   window.addEventListener("resize", onResize);
+ * }
+ * ```
+ */
+export declare const isServer: boolean;
+/**
+ * Build-time constant indicating whether code is running in a dev build.
+ * Replaced statically (`_SOLID_DEV_`) by the bundler integration, so guards
+ * like `if (isDev) {…}` are stripped from production builds.
+ *
+ * Use this to gate dev-only diagnostics, warnings, or expensive invariants
+ * that should never ship to production.
+ *
+ * @example
+ * ```ts
+ * import { isDev } from "@solidjs/web";
+ *
+ * if (isDev) {
+ *   console.warn("debug-only path");
+ * }
+ * ```
+ */
+export declare const isDev: boolean;
+type MountableElement = Element | Document | ShadowRoot | DocumentFragment | Node;
+export type IntrinsicElement = Extract<keyof JSX.IntrinsicElements, string>;
+export type ValidComponent = IntrinsicElement | Component<any> | (string & {});
+export type ComponentProps<T extends ValidComponent> = T extends Component<infer P> ? P : T extends keyof JSX.IntrinsicElements ? JSX.IntrinsicElements[T] : Record<string, unknown>;
+export type DynamicProps<T extends ValidComponent, P = ComponentProps<T>> = {
+    [K in keyof P]: P[K];
+} & {
+    component: T | null | undefined | false;
+};
+/**
+ * Renders a component tree into a DOM element. Returns a dispose function
+ * that tears the tree down and cleans up reactive scopes when called.
+ *
+ * @example
+ * ```tsx
+ * import { render } from "@solidjs/web";
+ *
+ * const dispose = render(() => <App />, document.getElementById("root")!);
+ *
+ * // Later, to unmount:
+ * dispose();
+ * ```
+ *
+ * @remarks
+ * The top-level insert is queued via `insertOptions: { schedule: true }` so
+ * its initial DOM attach goes through the effect queue rather than executing
+ * inline. This lets the mount participate in transitions: if an uncaught
+ * async read surfaces during the initial render (no `Loading` ancestor
+ * absorbs it), the mount is held by the transition and attaches atomically
+ * once all pending settles. On the no-async happy path the tail `flush()`
+ * drains the queued callback so the attach is synchronous by the time
+ * `render()` returns. The dev enforcement window scopes
+ * `ASYNC_OUTSIDE_LOADING_BOUNDARY` to the initial mount only.
+ */
+export declare function render(code: () => JSX.Element, element: MountableElement, init?: unknown, options?: {
+    renderId?: string;
+}): () => void;
+/**
+ * Resumes a server-rendered tree on the client, attaching event listeners
+ * and reactive bindings without reconstructing the DOM. Returns a `dispose`
+ * function that tears down reactive scopes (DOM nodes are left in place).
+ *
+ * Use this when the page HTML was produced by `renderToString`,
+ * `renderToStringAsync`, or `renderToStream`. For client-only apps, use
+ * `render` instead.
+ *
+ * Pass `options.renderId` to hydrate one of multiple roots emitted by a
+ * server render that used the same id.
+ *
+ * @example
+ * ```tsx
+ * import { hydrate } from "@solidjs/web";
+ *
+ * hydrate(() => <App />, document.getElementById("root")!);
+ * ```
+ */
+export declare const hydrate: typeof hydrateCore;
+/**
+ * Renders its children into a different part of the DOM (modal roots,
+ * tooltips, layers that need to escape an `overflow: hidden` ancestor).
+ *
+ * If `mount` is omitted, the portal attaches to `document.body`. The portal
+ * still participates in the parent's reactive scope and disposes when the
+ * parent does.
+ *
+ * Portals are client-only islands: the server renders nothing for them, and
+ * under hydration the children render fresh once hydration settles. Async
+ * read inside a portal therefore starts on the client — data that should be
+ * fetched on the server belongs above the portal (hoist the read, not the
+ * render), and async UI inside one wants its own `<Loading>` boundary.
+ *
+ * @example
+ * ```tsx
+ * <Portal mount={document.getElementById("modal-root")!}>
+ *   <Dialog />
+ * </Portal>
+ * ```
+ *
+ * @description https://docs.solidjs.com/reference/components/portal
+ */
+export declare function Portal(props: {
+    mount?: Element;
+    children: JSX.Element;
+}): JSX.Element;
+/**
+ * Returns a stable `Component` whose identity is driven by a reactive (and
+ * optionally async) `source`. The returned component can be used anywhere a
+ * normal component is used; children and props flow through JSX as usual.
+ *
+ * `source` may return a component, a native tag name (`'input'`, `'textarea'`,
+ * etc.), `undefined`, or a `Promise` of any of the above. A pending promise
+ * propagates as `NotReadyError` through the surrounding reactive scope, so
+ * async swaps compose with `<Loading>` boundaries the same way as `lazy`.
+ *
+ * @example
+ * ```tsx
+ * // `source` can return either a custom Component or a native tag
+ * // name — they're interchangeable, and the returned reference is a
+ * // stable Component you can use anywhere a normal one would go.
+ * const Field = dynamic(() => multiline() ? RichTextEditor : "input");
+ * return <Field value={value()} onInput={onInput} />;
+ * ```
+ *
+ * @description https://docs.solidjs.com/reference/components/dynamic
+ */
+export declare function dynamic<T extends ValidComponent>(source: () => T | Promise<T> | null | undefined | false): Component<ComponentProps<T>>;
+/**
+ * Renders an arbitrary custom or native component and forwards the other
+ * props. JSX form of `dynamic()` — same primitive, picked at the JSX site.
+ *
+ * @example
+ * ```tsx
+ * <Dynamic
+ *   component={multiline() ? RichTextEditor : "input"}
+ *   value={value()}
+ *   onInput={onInput}
+ * />
+ * ```
+ *
+ * @description https://docs.solidjs.com/reference/components/dynamic
+ */
+export declare function Dynamic<T extends ValidComponent>(props: DynamicProps<T>): JSX.Element;

package/types-cjs/jsx-properties.d.cts

@@ -0,0 +1,93 @@
+/**
+ * Shared type-level helpers used to derive `prop:*` attribute typings from
+ * DOM element interfaces (e.g. `HTMLInputElement`, `HTMLButtonElement`).
+ *
+ * The wrapping of each value (`FunctionMaybe<T>` in `jsx-h.d.ts` vs. the
+ * raw value in `jsx.d.ts`) is applied by each consumer when composing its
+ * own `Properties<T>` mapped type. That way this file stays identical in
+ * both reactive and non-reactive contexts and only needs to exist once.
+ *
+ * originally from
+ * @url https://github.com/potahtml/pota
+ */
+
+/** Base-class properties shared by all elements — skipped from `prop:*`. */
+export type SkipPropsFrom = HTMLUnknownElement & HTMLElement & Element & Node;
+
+/**
+ * Value types allowed on a `prop:*`. Primitives plus the writable
+ * non-primitive DOM-object props worth exposing:
+ *
+ * - `HTMLMediaElement.srcObject`
+ * - `HTMLButtonElement.popoverTargetElement` / `commandForElement` (and the same via
+ *   `PopoverTargetAttributes` mixin on `HTMLInputElement`)
+ */
+export type PropValue =
+  | string
+  | number
+  | boolean
+  | null
+  | MediaStream
+  | MediaSource
+  | Blob
+  | File
+  | Date
+  | Element;
+
+/**
+ * Ergonomics widening for emitted `prop:*` value types:
+ *
+ * - general `string` → `string | number` (HTML coerces numbers)
+ * - string literal unions (`'on' | 'off'`) stay exact, so users still get autocomplete /
+ *   narrowing
+ * - other types pass through unchanged
+ */
+type WidenString<V> = string extends V ? string | number : V;
+export type WidenPropValue<V> = [V] extends [string] ? WidenString<V> : V;
+
+/**
+ * Structurally identical → `Y`; distinct → `N`. Used by `IsReadonlyKey` to detect
+ * readonly keys by comparing `Pick<T, K>` with `Readonly<Pick<T, K>>`.
+ */
+export type IfEquals<A, B, Y = unknown, N = never> =
+  (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? Y : N;
+
+/**
+ * True when `K` is readonly on `T`. Singleton-constant properties (e.g.
+ * `tagName: "INPUT"`, `nodeType: 1`) are always `readonly` in `lib.dom.d.ts`, so this
+ * single check covers both readonly and singleton-literal cases.
+ */
+export type IsReadonlyKey<T, K extends keyof T> = IfEquals<
+  Pick<T, K>,
+  Readonly<Pick<T, K>>,
+  true,
+  false
+>;
+
+/**
+ * Resolves to the `prop:K` string literal when `K` is a writable, element-specific
+ * property suitable for a `prop:*` attribute; otherwise resolves to `never` so the
+ * key is filtered out of the resulting mapped type.
+ *
+ * Filters out:
+ *
+ * - base-class keys (via `SkipPropsFrom`)
+ * - aria-* keys (already typed via `AriaAttributes`)
+ * - readonly keys
+ * - keys whose value types fall outside `PropValue`
+ * - the generic `string` index signature (e.g. `HTMLFormElement[name: string]: any`),
+ *   which would otherwise shadow every key with an `any`-typed `prop:*`
+ */
+export type PropKey<T, K extends keyof T> = K extends keyof SkipPropsFrom
+  ? never
+  : K extends string
+    ? string extends K
+      ? never
+      : K extends `aria${string}`
+        ? never
+        : T[K] extends PropValue
+          ? IsReadonlyKey<T, K> extends true
+            ? never
+            : `prop:${K}`
+          : never
+    : never;