API 参考

Route action: handles form submissions for a page route.

Request header selecting the action response channel: `true` marks a programmatic caller and selects the serialized ActionResult union; `enhance` marks the built-in morph enhancement and selects the same full-HTML responses the no-JS path receives.

Context passed to a route action function (extends loader context).

formData: FormData (必填); request: Request (必填); params: Record<string, string> (必填); env: Env (必填); platform: Platform (必填); responseHeaders: Headers (必填) — Mutable response-only channel merged into the framework response.; route: Route (必填)

Wire shape returned to the JavaScript form-enhancement path (0.42.0-alpha.2). The no-JS path never sees this: it gets the equivalent semantics as plain HTTP (303 on success, 422 with the re-rendered form on validation failure, redirect/error as status codes). Error outcomes (CSRF 403, unknown action 404, unparseable body 400, unexpected 500) are NOT part of this union: since 0.42.0-alpha.13 (#863) they answer RFC 9457 Problem Details with the PROBLEM_JSON_MEDIA_TYPE content type — see ProblemDetails.

Application shell declaration: `false` disables the shell entirely, `'default'` uses the built-in shell, and the object form names a tag with the module path that defines it (`import`, resolved like a {@link FrameworkOptions.middleware.use } entry) plus the compiled shell properties the router injects per route.

Assert that a tag name is a valid custom element name.

Collect all public (non-internal) own properties from a host object. Keys starting with `__openElement` are framework-internal and excluded. Uses Reflect.get for safe access (respects getters); a getter that throws is skipped with a warning so one bad prop cannot take the tree down.

The per-tag verdict the compatibility scanner records: the tier a discovered tag was classified as, the human-readable `reason`, where the tag was found (`source`), and the SSR/DSD/hydration facts the verdict was derived from.

tagName: string (必填); tier: CompatibilityTier (必填); reason: string (必填); source: "local" | "package" | "nested" (必填); modulePath?: string (可选); ssr?: boolean (可选); dsd?: boolean (可选); hydrate?: string (可选)

How far a discovered tag may participate in the build: 'ssr-capable' renders and hydrates, 'client-only' ships to the browser without server output, 'experimental-dom' is admitted with a downgraded guarantee, and 'rejected' fails the build.

The delivery layer a component belongs to: fully static DSD markup ('dsd-static'), DSD markup with a client island ('dsd-interactive'), a client-only island with no SSR output ('pure-island'), or a light-DOM element ('light-dom'). Recorded per component in the build manifest and consumed by the hydration scheduler.

Create a derived read-only signal recomputed from its dependencies.

Consumer-local reactive projection of a protocol context value.

key.toString: () => string (必填) — Returns a string representation of an object.; key.valueOf: () => symbol (必填) — Returns the primitive value of the specified object.; key.description: string (必填) — Expose the [[Description]] internal slot of a symbol directly.; key.__@toPrimitive@413: (hint: string) => symbol (必填) — Converts a Symbol object to a symbol.; key.__@toStringTag@415: string (必填); defaultValue: T (必填)

A typed context token: protocol identity (`key`) plus its default value.

key.toString: () => string (必填) — Returns a string representation of an object.; key.valueOf: () => symbol (必填) — Returns the primitive value of the specified object.; key.description: string (必填) — Expose the [[Description]] internal slot of a symbol directly.; key.__@toPrimitive@413: (hint: string) => symbol (必填) — Converts a Symbol object to a symbol.; key.__@toStringTag@415: string (必填); defaultValue: T (必填)

Create a typed context token shared between provider and consumer elements.

toString: () => string (必填) — Returns a string representation of an object.; valueOf: () => symbol (必填) — Returns the primitive value of the specified object.; description: string (必填) — Expose the [[Description]] internal slot of a symbol directly.; __@toPrimitive@413: (hint: string) => symbol (必填) — Converts a Symbol object to a symbol.; __@toStringTag@415: string (必填)

Create one request-local deferred shell from a generated route manifest. The manifest hash is checked against the exact runtime wire program before any shell can be produced.

componentClass: CustomElementConstructor (必填); props?: Record<string, unknown> (可选); manifest: DeferredDsdManifest (必填); instanceId: string (必填); documentToken?: string (可选)

Inputs for a request-scoped deferred DSD server executor.

componentClass: CustomElementConstructor (必填); props?: Record<string, unknown> (可选); manifest: DeferredDsdManifest (必填); instanceId: string (必填); documentToken?: string (可选)

Create a {@link Logger} that prefixes every message with `[tag]`.

Object prototype keys that must never be injected from untrusted props.

Resolve `id` (a `#hash` or bare id) against `root` and, when the id is not in that root's own tree, recurse into every nested shadow root. Returns the first match or `null`; a malformed percent-encoded id is not an error.

Initial shell, typed seed, and bounded updates for a deferred DSD request.

shell: string (必填); owner: DeferredServerOwner (必填); seed: Record<string, { state: "resolved"; type: string; value: unknown; } | { state: "pending"; type: string; } | { state: "missing"; type: string; }> (必填); resolvedValue: (field: string, value: unknown) => unknown (必填); serializeResolved: (field: string, value: unknown) => string[] (必填)

Maps route-local deferred fields to the compiled Part or Region owners they update.

program: { version: number; tag: string; sha256: string; } (必填); fields: readonly { field: string; signal: string; owners: readonly { kind: "part" | "region"; index: number; }[]; }[] (必填)

The same document serialization boundary, with only body wrappers left open.

title?: string (可选); lang?: string (可选); clientScript?: string (可选); scripts?: DocumentScriptDescriptor[] (可选); meta.description?: string (可选); meta.tags?: Record<string, string | number | boolean>[] (可选); devScripts?: string (可选); headExtras?: string (可选); dangerouslyHeadFragments?: string[] (可选); allowHeadExtrasScripts?: boolean (可选); links?: { rel: string; href: string; hreflang?: string; }[] (可选); structuredData?: readonly Record<string, unknown>[] (可选); cspNonce?: string (可选); streamBootstrap?: string (可选) — Trusted framework bootstrap emitted synchronously in the document head.

Run a side effect that re-subscribes whenever its signal dependencies change.

Compiler-recognized element decorator; inert no-op at runtime.

Install (once per document) framework-level fragment navigation: a same-document anchor click whose target lives inside a nested shadow root scrolls to it and pushes the hash instead of being dropped by the browser. `{ enabled: false }` opts an application out.

enabled?: boolean (可选) — Set false before installation to opt out for an application.

Install the bounded pre-upgrade interaction capture on an owning root (default: the document). Generated client entries call this with their declared island tags before any compiled element upgrades; after a successful claim the element replays the captured events whose targets live inside its root (compiled claim capture/replay, internal/compiled/runtime.ts). Idempotent per root (repeat calls merge tags, never reinstall listeners) and a no-op where no DOM exists (SSR). Invariant: the capture itself — one fixed listener set per owning root, installed once per page — is page-lifetime by design and is NOT the leak. The M1 leak was retained event-target records; each element releases exactly its own records at its activation decision (success or failure), while records owned by still-pending elements survive for their delayed/lazy upgrade (#1170). Boundedness: the facade capture passes the declared-island filter, so only interactions under a still-pending DECLARED island tag enter the queue — ordinary events and undeclared third-party custom elements are skipped (nested pending declared islands still capture through their own unsettled host). With no tags declared the legacy dash heuristic applies. The queue additionally carries a hard capacity cap (fail closed) and every release sweeps detached targets, so post-hydration traffic and removals never grow retention.

addEventListener: (type: string, callback: EventListenerOrEventListenerObject | null, options?: AddEventListenerOptions | boolean) => void (必填) — The **`addEventListener()`** method of the EventTarget interface sets up a function that will be called whenever the specified event is delivered to the target. [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventTarget/addEventListener); dispatchEvent: (event: Event) => boolean (必填) — The **`dispatchEvent()`** method of the EventTarget sends an Event to the object, (synchronously) invoking the affected event listeners in the appropriate order. The normal event processing rules (including the capturing and optional bubbling phase) also apply to events dispatched manually with dispatchEvent(). [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventTarget/dispatchEvent); removeEventListener: (type: string, callback: EventListenerOrEventListenerObject | null, options?: EventListenerOptions | boolean) => void (必填) — The **`removeEventListener()`** method of the EventTarget interface removes an event listener previously registered with EventTarget.addEventListener() from the target. The event listener to be removed is identified using a combination of the event type, the event listener function itself, and various optional options that may affect the matching process; see Matching event listeners for removal.…

Error message prefix for all openElement errors.

Base class for elements that catch descendant render/hydration errors and apply a retry policy.

Callback receiving every reported {@linkcode OpenElementError} for telemetry.

Escape an HTML attribute value. Delegates to `escapeHtml` so both share the single `ESCAPE_MAP` and the same single-pass replacement (consolidated in v0.42.0-alpha.9, #633). Empty-value conventions remain intentionally distinct by design: - `escapeHtml` returns '' for non-string input. - `escapeAttrValue` (below) coerces via `String()` and is the boundary meant for unknown/variable attribute values.

Escape the five HTML-significant characters in text content.

Format an unknown thrown value as a human-readable string.

The adapter-facing framework options: where routes, islands and components live, which renderer serializes pages, the application shell and layout declarations, the document `<html>`/head injection channels, and the request-time middleware switches. Every field is optional; the adapter applies its documented default. This is the type an application config file's default export is checked against, so the rendered option table and the actual config surface cannot drift.

renderer?: "native" | "lit" (可选) — Page renderer selection (Beta.2.2, #1339). EXPLICIT, never inferred: 'native' (default) renders pages through the compiled Part Program serializer (renderDsd); 'lit' renders LitElement pages through; routesDir?: string (可选) — Directory the route scanner walks, relative to the Vite root. Defaults to `app/routes`.; islandsDir?: string (可选) — Directory island modules are discovered in. Defaults to `app/islands`.; componentsDir?: string (可选) — Directory non-route components live in. Defaults to `app/components`.; packageIslands?: string[] (可选) — Extra package names whose island modules the build admits, e.g. `['@openelement/ui']`.; appShell?: AppShellConfig (可选) — Application shell declaration; `false` disables the shell, `'default'` uses the built-in one.; layouts?: LayoutsConfig (可选) — Per-layout shell declarations keyed by layout name.; mode?: "ssg" (可选) — Build mode. 'ssg' (default) generates static HTML.; headExtras?: string (可选) — @dangerous injected as-is, only use with controlled content; html.lang?: string (可选); html.title?: string (可选); inject.stylesheets?: (string | { href: string; integrity?: string; crossorigin?: "anonymous" | "use-credentials"; attrs?: Record<string, string | number | boolean>; })[] (可选) — Stylesheets linked into the document head; each entry is an href or a link record with integrity/crossorigin/attrs.; inject.scripts?: (string | { src: string; type?: string; async?: boolean; defer?: boolean; integrity?: string; crossorigin?: "anonymous" | "use-credentials"; attrs?: Record<str… (可选) — Scripts emitted into the document; each entry is a src or a script record with type/async/defer/integrity/crossorigin/attrs.; inject.headFragments?: string[] (可选) — @dangerous fragments injected as-is. Trust boundary (same level as `trustedHtml`): never concatenate user-controlled content into these fragments; sanitize untrusted data at your own system boundary first. The framework only enforces no-`<script>` and no-executable-`<style>`.; ssr.noExternal?: (string | RegExp)[] (可选); island.upgradeStrategy?: "load" | "idle" | "visible" | "only" (可选); build.outDir?: string (可选) — Output directory for the build artifacts. Defaults to `dist`.; build.manifestBudget?: { islandKB?: number; totalJsKB?: number; pageKB?: number; } (可选) — Advisory only: exceeded budgets print build-manifest warnings and never fail the build; enforce them in your own build-output test.; viewTransition?: boolean (可选) — Enable the View Transitions API for client navigations. Defaults to true.; speculation?: boolean | { prerender?: string[]; prefetch?: string[]; exclude?: string[]; eagerness?: "immediate" | "moderate" | "conservative"; } (可选) — Speculation Rules emission: `true` uses framework defaults, or pass prerender/prefetch URL lists, exclusions and an eagerness.; middleware.cors?: boolean (可选) — Enable the built-in CORS middleware.; middleware.corsOrigin?: string | string[] (可选) — Static CORS allowlist data, serialized into the generated entry as JSON. Mutually exclusive with {@link FrameworkOptions.middleware.corsOriginModule }.; middleware.corsOriginModule?: string (可选) — Path to a module that default-exports `(origin: string) => string | undefined`. The generated entry imports the module — the callback is never serialized — so it may close over module scope and import dependencies. Resolved with the same idiom as `appShell.import` (e.g. './app/cors-origin.ts'). Mutually exclusive with `corsOrigin`.; middleware.requestId?: boolean (可选) — Emit and honor a per-request id header.; middleware.logger?: boolean (可选) — Log each request through the built-in logger.; middleware.securityHeaders?: boolean (可选) — Attach the built-in security response headers.; middleware.csp?: { policy?: string; nonce?: boolean; reportOnly?: boolean; } (可选) — Content-Security-Policy emission: the policy string, nonce generation, and report-only mode.; middleware.use?: string[] (可选) — Fetch middleware chain (#858), composed around the framework handler in onion order (`use[0]` outermost), outside all built-in middleware above. Each entry is a MODULE PATH (same resolution idiom as `appShell.import`, e.g. './app/middleware/auth.ts') whose default export is a {@link Middleware}; the generated entry emits `import * as __mw_N from '<path>'` and composes `__mw_N.default` in configur…

Runtime list of supported hydration strategies; the single source of truth for the `HydrationStrategy` union. Consumed by island/registry validation and re-exported from the element root for app and build adapters.

Island hydration trigger: 'load' | 'idle' | 'visible' | 'only'.

Safely assign caller-supplied props onto a target object, skipping keys that could enable prototype pollution and tolerating read-only properties. The canonical guarded assigner for the canonical dangerous-key rule (#903, #1214): the

Shared dangerous-key predicate (#903, #1214). Prototype-internal keys must never be injected from untrusted props on ANY path: host prop collection (collectPublicProps / normalizePublicProps in props-utils.ts), guarded assignment (injectPropsSafe below — the SPA bootstrap page-projection write boundary in

Per-island delivery options (hydration strategy, SSR/DSD participation).

hydrate?: "load" | "idle" | "visible" | "only" (可选) — Hydration strategy: - 'load': load immediately when module is imported - 'idle': defer to requestIdleCallback (default) - 'visible': use IntersectionObserver to defer until element is visible - 'only': client-only render, no DSD/SSR output Named `hydrate` to match `defineIslandConfig()` in the Router package — one option name across both packages.; dsd?: boolean (可选) — Whether to use DSD for SSR rendering of this island. Honored by the build-side island scan (via `defineIslandConfig`), not by `defineIsland()` itself: passing it in `IslandOptions` has no runtime effect.; ssr?: boolean (可选) — Whether this island may be admitted into server rendering. Like `dsd`, decided by the build-side island scan; inert when passed to `defineIsland()`.

Shared safe-attribute-name predicate (#1033). Attribute *names* are not escaped on any render path, so a name must be a valid HTML attribute name (blocks quote/space injection, #602) and must not be an event handler (`on*`, case-insensitive). render-ir.ts (silent skip) and Router tooling head-injection.ts (throw) enforce the same rule with different failure strategies; both delegate here so the boundary cannot diverge.

Check if a tag name is a valid custom element name per HTML spec.

Route loader: fetches data for a page route.

Context passed to a request-time ('dynamic') route loader.

request: Request (必填); params: Record<string, string> (必填); env: Env (必填); platform: Platform (必填); responseHeaders: Headers (必填) — Mutable response-only channel merged into the framework response.; route: Route (必填)

Locale-aware resolved path contract.

locale: string (必填); path: string (必填); localizedPath: string (必填); isDefaultLocalePath: boolean (必填)

logger.ts - Tagged console logger. Lightweight scoped logger. Returns plain functions so it is tree-shakable and has zero class overhead.

debug: (msg: string, ...args: unknown[]) => void (必填); info: (msg: string, ...args: unknown[]) => void (必填); warn: (msg: string, ...args: unknown[]) => void (必填); error: (msg: string, ...args: unknown[]) => void (必填)

Fetch middleware contract (#858): WinterCG shape, dialect-free — no Hono/h3 context object. Composed at the handler boundary in onion order (`use[0]` is outermost: it sees the request first and the response last), so it runs with identical semantics in the dev server, the `start` CLI, the e2e fixture server, and the Nitro production entry. A middleware may short-circuit by returning a Response without calling `next()`, or post-process the Response that `next()` returns. Module contract: a Middleware is the DEFAULT EXPORT of a module referenced from `middleware.use` by path (e.g. './app/middleware/auth.ts'). The generated server entry imports the module, so the middleware may close over module scope and import local helpers and third-party packages — it is a real module in the server module graph, never serialized source.

Custom Element base class for the compiled Part Program architecture. Subclasses are produced by the 0.44 compiler; hand-written subclasses that never pass through the compiler fail closed at connect time.

One documented attribute of a custom element declaration.

name: string (必填); type?: string (可选); default?: string (可选); description?: string (可选); reflects?: boolean (可选); fieldName?: string (可选)

One documented CSS part of a custom element declaration.

name: string (必填); description?: string (可选)

One custom element declaration in a package manifest: tag, members and delivery metadata.

tagName: string (必填); className?: string (可选); superclassName?: string (可选); attributes?: OpenElementAttribute[] (可选); events?: OpenElementEvent[] (可选); slots?: OpenElementSlot[] (可选); cssParts?: OpenElementCssPart[] (可选); openElement.ssr?: boolean (可选); openElement.dsd?: boolean (可选); openElement.layer?: ComponentLayer (可选); openElement.hydrate?: "load" | "idle" | "visible" | "only" (可选); openElement.module?: string (可选); openElement.export?: string (可选); description?: string (可选)

Framework error carrying a stable code, severity, phase and recoverability contract.

One documented custom event of a custom element declaration.

name: string (必填); type?: string (可选); description?: string (可选)

Package manifest of component declarations (not a Custom Elements Manifest).

schemaVersion: string (必填); packageName: string (必填); version: string (必填); description?: string (可选); author?: string (可选); license?: string (可选); homepage?: string (可选); repository?: string (可选); declarations: OpenElementDeclaration[] (必填)

Host-agnostic route and asset contracts shared by app and build drivers.

One node of the host-agnostic route tree: the matched URL `path` and route kind, the source and module paths the drivers resolve, the optional registered tag and param names, and the nested `children`.

kind: OpenElementRouteKind (必填); path: string (必填); filePath?: string (可选); importPath?: string (可选); tagName?: string (可选); paramNames?: string[] (可选); children?: OpenElementRouteNode[] (可选); meta?: Record<string, unknown> (可选)

One documented slot of a custom element declaration.

name: string (必填); description?: string (可选)

Media type of the RFC 9457 action error channel (#863).

RFC 9457 Problem Details document (0.42.0-alpha.13, #863): the action error channel answers `application/problem+json` instead of the bespoke `{ type: 'error', error: { message } }` JSON, so HTTP tooling recognizes failures natively. With `type: 'about:blank'`, `title` is the HTTP reason phrase and `detail` carries the specific explanation. The wire shape is alpha-unfrozen; the 1.0 acceptance freezes it in this problem+json form.

type: string (必填) — URI reference identifying the problem type; 'about:blank' when none applies.; title: string (必填) — Short human-readable summary (the HTTP reason phrase for 'about:blank').; status.toString: (radix?: number) => string (必填) — Returns a string representation of an object.; status.toFixed: (fractionDigits?: number) => string (必填) — Returns a string representing a number in fixed-point notation.; status.toExponential: (fractionDigits?: number) => string (必填) — Returns a string containing a number represented in exponential notation.; status.toPrecision: (precision?: number) => string (必填) — Returns a string containing a number represented either in exponential or fixed-point notation with a specified number of digits.; status.valueOf: () => number (必填) — Returns the primitive value of the specified object.; status.toLocaleString: { (locales?: string | string[], options?: Intl.NumberFormatOptions): string; (locales?: Intl.LocalesArgument, options?: Intl.NumberFormatOptions): string; } (必填) — Converts a number to a string by using the current or specified locale.; detail?: string (可选) — Human-readable explanation specific to this occurrence.

Compiler-recognized property decorator; inert no-op at runtime.

reflect: boolean (必填); attribute?: string | false (可选); type?: unknown (可选); converter?: unknown (可选)

Provide a plain protocol value; the provider Signal remains OE-private.

Read-only signal protocol used by computed values.

value: T (必填); subscribe: (fn: (value: T) => void) => Unsubscribe (必填); __@SIGNAL_BRAND@527.valueOf: () => boolean (必填) — Returns the primitive value of the specified object.

Server-render one compiled element through canonical Element composition.

Options for one `renderDsd()` call: the compiled component class to serialize, the values projected onto its compiled properties, optional route/source diagnostics metadata, the nested compiled tags the build admitted, and trusted parent-owned light children keyed by slot name.

componentClass?: CustomElementConstructor (可选); props?: Record<string, unknown> (可选); sourceInfo.route?: string (可选); sourceInfo.source?: string (可选); ssrRenderableTags?: readonly string[] (可选) — Build-admitted nested compiled tags. Omitted means shell-only rendering.; projectedChildren?: ReadonlyMap<string, TrustedHtml> (可选) — Trusted parent-owned light children keyed by slot name.

Recoverable render-phase error carrying the failing component path and tag.

The public result of one `renderDsd()` call: the serialized DSD `html`, the render errors collected while composing it (empty on success), the render metrics for the root component, and the hydration hints the client scheduler reads to upgrade islands.

html: string (必填); errors: RenderError[] (必填); metrics: DsdRenderMetrics (必填); hydrationHints: HydrationHint[] (必填)

Report an {@linkcode OpenElementError} to the telemetry hook, or console.error when none is installed.

code: string (必填); severity: ErrorSeverity (必填); phase: ErrorPhase (必填); recoverable: boolean (必填); statusCode.toString: (radix?: number) => string (必填) — Returns a string representation of an object.; statusCode.toFixed: (fractionDigits?: number) => string (必填) — Returns a string representing a number in fixed-point notation.; statusCode.toExponential: (fractionDigits?: number) => string (必填) — Returns a string containing a number represented in exponential notation.; statusCode.toPrecision: (precision?: number) => string (必填) — Returns a string containing a number represented either in exponential or fixed-point notation with a specified number of digits.; statusCode.valueOf: () => number (必填) — Returns the primitive value of the specified object.; statusCode.toLocaleString: { (locales?: string | string[], options?: Intl.NumberFormatOptions): string; (locales?: Intl.LocalesArgument, options?: Intl.NumberFormatOptions): string; } (必填) — Converts a number to a string by using the current or specified locale.; toJSON: () => Record<string, unknown> (必填); name: string (必填); message: string (必填); stack?: string (可选); cause?: unknown (可选)

One route admitted by the scanner: URL `path`, source `filePath`, the route `type`, the generated variable name (`varName`) the entry binds it to, and the optional registration tag. {@link RouteEntry.definePage} and {@link RouteEntry.hasEnhancedForms} carry the two source-derived admission facts the generated entries branch on.

path: string (必填); filePath: string (必填); type: "page" | "api" | "island" | "special" (必填); varName: string (必填); tagName?: string (可选); definePage?: boolean (可选) — True when the route module's default export is a definePage() definition (0.42.0-alpha.17, #960 — registration decoupling). The generated entry registers the page class under the path-derived fallback tag and IGNORES the tagName export for registration: on a definePage route the export only names a content element. Plain element routes keep tagName as their registration tag.; source?: string (可选) — Source text captured during scanning when includeSource is enabled.; hasEnhancedForms?: boolean (可选) — True when the page route source carries data-open-enhance (0.42.0-alpha.5, #569): the client entry must ship the form-enhancement layer even when the app has zero islands.; special?: SpecialFileType (可选); params?: string[] (可选)

Canonical request-time/SSG server route context.

request: Request (必填); params: Record<string, string> (必填); env: Env (必填); platform: Platform (必填); responseHeaders: Headers (必填) — Mutable response-only channel merged into the framework response.; route: Route (必填)

Context passed to a request-time ('dynamic') route loader. This is the server contract: the loader runs on the server with the Web-standard request, matched route params, the host environment and the platform object, and signals validation failure via fail()/redirect().

path: string (必填); filePath: string (必填)

Install the process-wide error telemetry hook (replaceable for tests, HMR, multi-app pages).

Create a writable signal through the selected signal engine.

Alias for APIs that accept either writable or read-only signals.

Special file kinds the route scanner recognizes by filename: `renderer` and `middleware`.

The build's admission verdict for one discovered tag: where the declaration lives (`modulePath`), how it was discovered (`source`), which render path it is admitted to, and the reason recorded for the manifest.

tagName: string (必填); modulePath: string (必填) — Module path of the island declaration. Empty for 'foreign' decisions: a foreign tag is consumed in JSX but declares no module the build owns.; source: "local" | "package" | "nested" | "foreign" (必填) — 'foreign' (#979, 0.43.0-alpha.2): a third-party WC tag discovered by the foreign-tag scanner in page/island JSX — recorded for visibility only; SSR still treats it as an opaque passthrough (renderPath 'client-only').; renderPath: "ssr+client" | "client-only" | "rejected" (必填); reason: string (必填)

Tags a deferred frame cannot safely install into an owned Part range: the browser installer rejects any frame whose markup carries one of these.

Schemes that make a URL attribute unsafe in a streamed frame.

URL-carrying attributes the frame check screens for script-bearing scheme obfuscation; only these attribute names are value-screened.

Control characters at or below this code point are stripped before the URL-scheme test, so tab/newline/control obfuscation cannot smuggle a scheme past admission.

Cross-realm StyleSheet constructor: the native CSSStyleSheet or the internal shim.

Minimal stylesheet contract (replaceSync + cssRules) satisfied by native and shim sheets.

replaceSync: (text: string) => void (必填); cssRules: StyleSheetRule[] (必填)

Mark an HTML string as trusted for explicit `innerHTML` sinks (the trust does not serialize).

Opaque capability marking HTML the application has explicitly vetted as trusted.

html: string (必填)

Whether a static attribute (name/value as authored into the Part Program) makes a streamed frame unsafely installable: event-handler, seed-spoofing, and srcdoc names fail outright, and URL-carrying names fail when the entity-decoded, control-stripped value carries a script scheme.

Wrap rendered HTML in a full HTML document. Adds DOCTYPE, head (title, meta, preload), and body. Supports CSP nonce and dev scripts (e.g. Vite client, route module registration).

Request header selecting the action response channel: `true` marks a programmatic caller and selects the serialized ActionResult union; `enhance` marks the built-in morph enhancement and selects the same full-HTML responses the no-JS path receives.

Assert that a tag name is a valid custom element name.

Object prototype keys that must never be injected from untrusted props.

Error message prefix for all openElement errors.

Runtime list of supported hydration strategies; the single source of truth for the `HydrationStrategy` union. Consumed by island/registry validation and re-exported from the element root for app and build adapters.

Island hydration trigger: 'load' | 'idle' | 'visible' | 'only'.

Safely assign caller-supplied props onto a target object, skipping keys that could enable prototype pollution and tolerating read-only properties. The canonical guarded assigner for the canonical dangerous-key rule (#903, #1214): the

Shared dangerous-key predicate (#903, #1214). Prototype-internal keys must never be injected from untrusted props on ANY path: host prop collection (collectPublicProps / normalizePublicProps in props-utils.ts), guarded assignment (injectPropsSafe below — the SPA bootstrap page-projection write boundary in

Shared safe-attribute-name predicate (#1033). Attribute *names* are not escaped on any render path, so a name must be a valid HTML attribute name (blocks quote/space injection, #602) and must not be an event handler (`on*`, case-insensitive). render-ir.ts (silent skip) and Router tooling head-injection.ts (throw) enforce the same rule with different failure strategies; both delegate here so the boundary cannot diverge.

Check if a tag name is a valid custom element name per HTML spec.

Framework error carrying a stable code, severity, phase and recoverability contract.

Media type of the RFC 9457 action error channel (#863).

Compose a fetch middleware chain (#858) around a handler, in onion order: `middleware[0]` is outermost — it sees the request first and the response last. A middleware may short-circuit by returning a Response without calling `next()`. Extra arguments (runtime context such as env/platform) thread transparently past the middleware chain to the terminal handler — the WinterCG-shaped middleware itself only ever sees `(request, next)`. Generated server entries call this once at module scope so the dev server, the `start` CLI, the e2e fixture server, and the Nitro production entry all share the same composed handler.

Normalize a runtime adapter declaration: pass the name, fetch handler and optional prerender iterator through unchanged so a host integration only implements the {@link RuntimeAdapter} contract it needs.

name: string (必填); fetch: OpenElementRequestHandler<Env> (必填); prerender?: (() => AsyncIterable<RuntimePrerenderResult> | Iterable<RuntimePrerenderResult>) (可选)

Serialize a value to pretty-printed JSON ending with a newline.

Insert markup before a tolerant HTML body close (`</body >`, case-insensitive).

Normalize path separators and collapse duplicates. - Backslashes and forward slashes are replaced with the chosen separator. - Repeated separators are collapsed to a single separator.

The host-neutral request handler every runtime adapter and generated server entry exposes: a WinterCG `(request, context?) => Response` with no server engine dialect baked in.

Convert a file path into a kebab-cased custom element tag name. - Removes a leading `./` or `/`. - Strips known file extensions (`ts`, `tsx`, `js`, `jsx`, `mjs`, `mdx`). - Replaces directory separators with hyphens. - Ensures the result starts with a letter and contains at least one hyphen.

runtime.ts - Runtime adapter protocol. Replacement boundary for Nitro, Workers, Node, Deno, or future fetch-compatible runtimes. Preserves openElement semantics while leaving concrete server engines outside this package.

env?: Env (可选); platform?: unknown (可选); params?: Record<string, string> (可选)

Thrown by the SSG build pipeline when the SSR bundle fails to load or the pipeline throws; re-exported via `@openelement/element/build-utils`. Carries the failing component path plus the original error as `cause`.

Inject island metadata markers into source code. Only transforms files inside the islands directory. Tag names are derived from the file path and normalized to valid custom element names (lowercase letters, digits, and hyphens). Unsafe characters are silently normalized to hyphens.

Route action: handles form submissions for a page route.

Request header selecting the action response channel: `true` marks a programmatic caller and selects the serialized ActionResult union; `enhance` marks the built-in morph enhancement and selects the same full-HTML responses the no-JS path receives.

Context passed to a route action function (extends loader context).

formData: FormData (必填); request: Request (必填); params: Record<string, string> (必填); env: Env (必填); platform: Platform (必填); responseHeaders: Headers (必填) — Mutable response-only channel merged into the framework response.; route: Route (必填)

Wire shape returned to the JavaScript form-enhancement path (0.42.0-alpha.2). The no-JS path never sees this: it gets the equivalent semantics as plain HTTP (303 on success, 422 with the re-rendered form on validation failure, redirect/error as status codes). Error outcomes (CSRF 403, unknown action 404, unparseable body 400, unexpected 500) are NOT part of this union: since 0.42.0-alpha.13 (#863) they answer RFC 9457 Problem Details with the PROBLEM_JSON_MEDIA_TYPE content type — see ProblemDetails.

Application shell declaration: `false` disables the shell entirely, `'default'` uses the built-in shell, and the object form names a tag with the module path that defines it (`import`, resolved like a {@link FrameworkOptions.middleware.use } entry) plus the compiled shell properties the router injects per route.

Assert that a tag name is a valid custom element name.

Collect all public (non-internal) own properties from a host object. Keys starting with `__openElement` are framework-internal and excluded. Uses Reflect.get for safe access (respects getters); a getter that throws is skipped with a warning so one bad prop cannot take the tree down.

The per-tag verdict the compatibility scanner records: the tier a discovered tag was classified as, the human-readable `reason`, where the tag was found (`source`), and the SSR/DSD/hydration facts the verdict was derived from.

tagName: string (必填); tier: CompatibilityTier (必填); reason: string (必填); source: "local" | "package" | "nested" (必填); modulePath?: string (可选); ssr?: boolean (可选); dsd?: boolean (可选); hydrate?: string (可选)

How far a discovered tag may participate in the build: 'ssr-capable' renders and hydrates, 'client-only' ships to the browser without server output, 'experimental-dom' is admitted with a downgraded guarantee, and 'rejected' fails the build.

The delivery layer a component belongs to: fully static DSD markup ('dsd-static'), DSD markup with a client island ('dsd-interactive'), a client-only island with no SSR output ('pure-island'), or a light-DOM element ('light-dom'). Recorded per component in the build manifest and consumed by the hydration scheduler.

Create a derived read-only signal recomputed from its dependencies.

Consumer-local reactive projection of a protocol context value.

key.toString: () => string (必填) — Returns a string representation of an object.; key.valueOf: () => symbol (必填) — Returns the primitive value of the specified object.; key.description: string (必填) — Expose the [[Description]] internal slot of a symbol directly.; key.__@toPrimitive@1738: (hint: string) => symbol (必填) — Converts a Symbol object to a symbol.; key.__@toStringTag@1740: string (必填); defaultValue: T (必填)

A typed context token: protocol identity (`key`) plus its default value.

key.toString: () => string (必填) — Returns a string representation of an object.; key.valueOf: () => symbol (必填) — Returns the primitive value of the specified object.; key.description: string (必填) — Expose the [[Description]] internal slot of a symbol directly.; key.__@toPrimitive@1738: (hint: string) => symbol (必填) — Converts a Symbol object to a symbol.; key.__@toStringTag@1740: string (必填); defaultValue: T (必填)

Create a typed context token shared between provider and consumer elements.

toString: () => string (必填) — Returns a string representation of an object.; valueOf: () => symbol (必填) — Returns the primitive value of the specified object.; description: string (必填) — Expose the [[Description]] internal slot of a symbol directly.; __@toPrimitive@1738: (hint: string) => symbol (必填) — Converts a Symbol object to a symbol.; __@toStringTag@1740: string (必填)

Create one request-local deferred shell from a generated route manifest. The manifest hash is checked against the exact runtime wire program before any shell can be produced.

componentClass: CustomElementConstructor (必填); props?: Record<string, unknown> (可选); manifest: DeferredDsdManifest (必填); instanceId: string (必填); documentToken?: string (可选)

Inputs for a request-scoped deferred DSD server executor.

componentClass: CustomElementConstructor (必填); props?: Record<string, unknown> (可选); manifest: DeferredDsdManifest (必填); instanceId: string (必填); documentToken?: string (可选)

Create a {@link Logger} that prefixes every message with `[tag]`.

Object prototype keys that must never be injected from untrusted props.

Resolve `id` (a `#hash` or bare id) against `root` and, when the id is not in that root's own tree, recurse into every nested shadow root. Returns the first match or `null`; a malformed percent-encoded id is not an error.

Initial shell, typed seed, and bounded updates for a deferred DSD request.

shell: string (必填); owner: DeferredServerOwner (必填); seed: Record<string, { state: "resolved"; type: string; value: unknown; } | { state: "pending"; type: string; } | { state: "missing"; type: string; }> (必填); resolvedValue: (field: string, value: unknown) => unknown (必填); serializeResolved: (field: string, value: unknown) => string[] (必填)

Maps route-local deferred fields to the compiled Part or Region owners they update.

program: { version: number; tag: string; sha256: string; } (必填); fields: readonly { field: string; signal: string; owners: readonly { kind: "part" | "region"; index: number; }[]; }[] (必填)

The same document serialization boundary, with only body wrappers left open.

title?: string (可选); lang?: string (可选); clientScript?: string (可选); scripts?: DocumentScriptDescriptor[] (可选); meta.description?: string (可选); meta.tags?: Record<string, string | number | boolean>[] (可选); devScripts?: string (可选); headExtras?: string (可选); dangerouslyHeadFragments?: string[] (可选); allowHeadExtrasScripts?: boolean (可选); links?: { rel: string; href: string; hreflang?: string; }[] (可选); structuredData?: readonly Record<string, unknown>[] (可选); cspNonce?: string (可选); streamBootstrap?: string (可选) — Trusted framework bootstrap emitted synchronously in the document head.

Run a side effect that re-subscribes whenever its signal dependencies change.

Compiler-recognized element decorator; inert no-op at runtime.

Install (once per document) framework-level fragment navigation: a same-document anchor click whose target lives inside a nested shadow root scrolls to it and pushes the hash instead of being dropped by the browser. `{ enabled: false }` opts an application out.

enabled?: boolean (可选) — Set false before installation to opt out for an application.

Install the bounded pre-upgrade interaction capture on an owning root (default: the document). Generated client entries call this with their declared island tags before any compiled element upgrades; after a successful claim the element replays the captured events whose targets live inside its root (compiled claim capture/replay, internal/compiled/runtime.ts). Idempotent per root (repeat calls merge tags, never reinstall listeners) and a no-op where no DOM exists (SSR). Invariant: the capture itself — one fixed listener set per owning root, installed once per page — is page-lifetime by design and is NOT the leak. The M1 leak was retained event-target records; each element releases exactly its own records at its activation decision (success or failure), while records owned by still-pending elements survive for their delayed/lazy upgrade (#1170). Boundedness: the facade capture passes the declared-island filter, so only interactions under a still-pending DECLARED island tag enter the queue — ordinary events and undeclared third-party custom elements are skipped (nested pending declared islands still capture through their own unsettled host). With no tags declared the legacy dash heuristic applies. The queue additionally carries a hard capacity cap (fail closed) and every release sweeps detached targets, so post-hydration traffic and removals never grow retention.

addEventListener: (type: string, callback: EventListenerOrEventListenerObject | null, options?: AddEventListenerOptions | boolean) => void (必填) — The **`addEventListener()`** method of the EventTarget interface sets up a function that will be called whenever the specified event is delivered to the target. [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventTarget/addEventListener); dispatchEvent: (event: Event) => boolean (必填) — The **`dispatchEvent()`** method of the EventTarget sends an Event to the object, (synchronously) invoking the affected event listeners in the appropriate order. The normal event processing rules (including the capturing and optional bubbling phase) also apply to events dispatched manually with dispatchEvent(). [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventTarget/dispatchEvent); removeEventListener: (type: string, callback: EventListenerOrEventListenerObject | null, options?: EventListenerOptions | boolean) => void (必填) — The **`removeEventListener()`** method of the EventTarget interface removes an event listener previously registered with EventTarget.addEventListener() from the target. The event listener to be removed is identified using a combination of the event type, the event listener function itself, and various optional options that may affect the matching process; see Matching event listeners for removal.…

Error message prefix for all openElement errors.

Base class for elements that catch descendant render/hydration errors and apply a retry policy.

Callback receiving every reported {@linkcode OpenElementError} for telemetry.

Escape an HTML attribute value. Delegates to `escapeHtml` so both share the single `ESCAPE_MAP` and the same single-pass replacement (consolidated in v0.42.0-alpha.9, #633). Empty-value conventions remain intentionally distinct by design: - `escapeHtml` returns '' for non-string input. - `escapeAttrValue` (below) coerces via `String()` and is the boundary meant for unknown/variable attribute values.

Escape the five HTML-significant characters in text content.

Format an unknown thrown value as a human-readable string.

The adapter-facing framework options: where routes, islands and components live, which renderer serializes pages, the application shell and layout declarations, the document `<html>`/head injection channels, and the request-time middleware switches. Every field is optional; the adapter applies its documented default. This is the type an application config file's default export is checked against, so the rendered option table and the actual config surface cannot drift.

renderer?: "native" | "lit" (可选) — Page renderer selection (Beta.2.2, #1339). EXPLICIT, never inferred: 'native' (default) renders pages through the compiled Part Program serializer (renderDsd); 'lit' renders LitElement pages through; routesDir?: string (可选) — Directory the route scanner walks, relative to the Vite root. Defaults to `app/routes`.; islandsDir?: string (可选) — Directory island modules are discovered in. Defaults to `app/islands`.; componentsDir?: string (可选) — Directory non-route components live in. Defaults to `app/components`.; packageIslands?: string[] (可选) — Extra package names whose island modules the build admits, e.g. `['@openelement/ui']`.; appShell?: AppShellConfig (可选) — Application shell declaration; `false` disables the shell, `'default'` uses the built-in one.; layouts?: LayoutsConfig (可选) — Per-layout shell declarations keyed by layout name.; mode?: "ssg" (可选) — Build mode. 'ssg' (default) generates static HTML.; headExtras?: string (可选) — @dangerous injected as-is, only use with controlled content; html.lang?: string (可选); html.title?: string (可选); inject.stylesheets?: (string | { href: string; integrity?: string; crossorigin?: "anonymous" | "use-credentials"; attrs?: Record<string, string | number | boolean>; })[] (可选) — Stylesheets linked into the document head; each entry is an href or a link record with integrity/crossorigin/attrs.; inject.scripts?: (string | { src: string; type?: string; async?: boolean; defer?: boolean; integrity?: string; crossorigin?: "anonymous" | "use-credentials"; attrs?: Record<str… (可选) — Scripts emitted into the document; each entry is a src or a script record with type/async/defer/integrity/crossorigin/attrs.; inject.headFragments?: string[] (可选) — @dangerous fragments injected as-is. Trust boundary (same level as `trustedHtml`): never concatenate user-controlled content into these fragments; sanitize untrusted data at your own system boundary first. The framework only enforces no-`<script>` and no-executable-`<style>`.; ssr.noExternal?: (string | RegExp)[] (可选); island.upgradeStrategy?: "load" | "idle" | "visible" | "only" (可选); build.outDir?: string (可选) — Output directory for the build artifacts. Defaults to `dist`.; build.manifestBudget?: { islandKB?: number; totalJsKB?: number; pageKB?: number; } (可选) — Advisory only: exceeded budgets print build-manifest warnings and never fail the build; enforce them in your own build-output test.; viewTransition?: boolean (可选) — Enable the View Transitions API for client navigations. Defaults to true.; speculation?: boolean | { prerender?: string[]; prefetch?: string[]; exclude?: string[]; eagerness?: "immediate" | "moderate" | "conservative"; } (可选) — Speculation Rules emission: `true` uses framework defaults, or pass prerender/prefetch URL lists, exclusions and an eagerness.; middleware.cors?: boolean (可选) — Enable the built-in CORS middleware.; middleware.corsOrigin?: string | string[] (可选) — Static CORS allowlist data, serialized into the generated entry as JSON. Mutually exclusive with {@link FrameworkOptions.middleware.corsOriginModule }.; middleware.corsOriginModule?: string (可选) — Path to a module that default-exports `(origin: string) => string | undefined`. The generated entry imports the module — the callback is never serialized — so it may close over module scope and import dependencies. Resolved with the same idiom as `appShell.import` (e.g. './app/cors-origin.ts'). Mutually exclusive with `corsOrigin`.; middleware.requestId?: boolean (可选) — Emit and honor a per-request id header.; middleware.logger?: boolean (可选) — Log each request through the built-in logger.; middleware.securityHeaders?: boolean (可选) — Attach the built-in security response headers.; middleware.csp?: { policy?: string; nonce?: boolean; reportOnly?: boolean; } (可选) — Content-Security-Policy emission: the policy string, nonce generation, and report-only mode.; middleware.use?: string[] (可选) — Fetch middleware chain (#858), composed around the framework handler in onion order (`use[0]` outermost), outside all built-in middleware above. Each entry is a MODULE PATH (same resolution idiom as `appShell.import`, e.g. './app/middleware/auth.ts') whose default export is a {@link Middleware}; the generated entry emits `import * as __mw_N from '<path>'` and composes `__mw_N.default` in configur…

Runtime list of supported hydration strategies; the single source of truth for the `HydrationStrategy` union. Consumed by island/registry validation and re-exported from the element root for app and build adapters.

Island hydration trigger: 'load' | 'idle' | 'visible' | 'only'.

Safely assign caller-supplied props onto a target object, skipping keys that could enable prototype pollution and tolerating read-only properties. The canonical guarded assigner for the canonical dangerous-key rule (#903, #1214): the

Shared dangerous-key predicate (#903, #1214). Prototype-internal keys must never be injected from untrusted props on ANY path: host prop collection (collectPublicProps / normalizePublicProps in props-utils.ts), guarded assignment (injectPropsSafe below — the SPA bootstrap page-projection write boundary in

Per-island delivery options (hydration strategy, SSR/DSD participation).

hydrate?: "load" | "idle" | "visible" | "only" (可选) — Hydration strategy: - 'load': load immediately when module is imported - 'idle': defer to requestIdleCallback (default) - 'visible': use IntersectionObserver to defer until element is visible - 'only': client-only render, no DSD/SSR output Named `hydrate` to match `defineIslandConfig()` in the Router package — one option name across both packages.; dsd?: boolean (可选) — Whether to use DSD for SSR rendering of this island. Honored by the build-side island scan (via `defineIslandConfig`), not by `defineIsland()` itself: passing it in `IslandOptions` has no runtime effect.; ssr?: boolean (可选) — Whether this island may be admitted into server rendering. Like `dsd`, decided by the build-side island scan; inert when passed to `defineIsland()`.

Shared safe-attribute-name predicate (#1033). Attribute *names* are not escaped on any render path, so a name must be a valid HTML attribute name (blocks quote/space injection, #602) and must not be an event handler (`on*`, case-insensitive). render-ir.ts (silent skip) and Router tooling head-injection.ts (throw) enforce the same rule with different failure strategies; both delegate here so the boundary cannot diverge.

Check if a tag name is a valid custom element name per HTML spec.

Route loader: fetches data for a page route.

Context passed to a request-time ('dynamic') route loader.

request: Request (必填); params: Record<string, string> (必填); env: Env (必填); platform: Platform (必填); responseHeaders: Headers (必填) — Mutable response-only channel merged into the framework response.; route: Route (必填)

Locale-aware resolved path contract.

locale: string (必填); path: string (必填); localizedPath: string (必填); isDefaultLocalePath: boolean (必填)

logger.ts - Tagged console logger. Lightweight scoped logger. Returns plain functions so it is tree-shakable and has zero class overhead.

debug: (msg: string, ...args: unknown[]) => void (必填); info: (msg: string, ...args: unknown[]) => void (必填); warn: (msg: string, ...args: unknown[]) => void (必填); error: (msg: string, ...args: unknown[]) => void (必填)

Fetch middleware contract (#858): WinterCG shape, dialect-free — no Hono/h3 context object. Composed at the handler boundary in onion order (`use[0]` is outermost: it sees the request first and the response last), so it runs with identical semantics in the dev server, the `start` CLI, the e2e fixture server, and the Nitro production entry. A middleware may short-circuit by returning a Response without calling `next()`, or post-process the Response that `next()` returns. Module contract: a Middleware is the DEFAULT EXPORT of a module referenced from `middleware.use` by path (e.g. './app/middleware/auth.ts'). The generated server entry imports the module, so the middleware may close over module scope and import local helpers and third-party packages — it is a real module in the server module graph, never serialized source.

Custom Element base class for the compiled Part Program architecture. Subclasses are produced by the 0.44 compiler; hand-written subclasses that never pass through the compiler fail closed at connect time.

One documented attribute of a custom element declaration.

name: string (必填); type?: string (可选); default?: string (可选); description?: string (可选); reflects?: boolean (可选); fieldName?: string (可选)

One documented CSS part of a custom element declaration.

name: string (必填); description?: string (可选)

One custom element declaration in a package manifest: tag, members and delivery metadata.

tagName: string (必填); className?: string (可选); superclassName?: string (可选); attributes?: OpenElementAttribute[] (可选); events?: OpenElementEvent[] (可选); slots?: OpenElementSlot[] (可选); cssParts?: OpenElementCssPart[] (可选); openElement.ssr?: boolean (可选); openElement.dsd?: boolean (可选); openElement.layer?: ComponentLayer (可选); openElement.hydrate?: "load" | "idle" | "visible" | "only" (可选); openElement.module?: string (可选); openElement.export?: string (可选); description?: string (可选)

Framework error carrying a stable code, severity, phase and recoverability contract.

One documented custom event of a custom element declaration.

name: string (必填); type?: string (可选); description?: string (可选)

Package manifest of component declarations (not a Custom Elements Manifest).

schemaVersion: string (必填); packageName: string (必填); version: string (必填); description?: string (可选); author?: string (可选); license?: string (可选); homepage?: string (可选); repository?: string (可选); declarations: OpenElementDeclaration[] (必填)

Host-agnostic route and asset contracts shared by app and build drivers.

One node of the host-agnostic route tree: the matched URL `path` and route kind, the source and module paths the drivers resolve, the optional registered tag and param names, and the nested `children`.

kind: OpenElementRouteKind (必填); path: string (必填); filePath?: string (可选); importPath?: string (可选); tagName?: string (可选); paramNames?: string[] (可选); children?: OpenElementRouteNode[] (可选); meta?: Record<string, unknown> (可选)

One documented slot of a custom element declaration.

name: string (必填); description?: string (可选)

Media type of the RFC 9457 action error channel (#863).

RFC 9457 Problem Details document (0.42.0-alpha.13, #863): the action error channel answers `application/problem+json` instead of the bespoke `{ type: 'error', error: { message } }` JSON, so HTTP tooling recognizes failures natively. With `type: 'about:blank'`, `title` is the HTTP reason phrase and `detail` carries the specific explanation. The wire shape is alpha-unfrozen; the 1.0 acceptance freezes it in this problem+json form.

type: string (必填) — URI reference identifying the problem type; 'about:blank' when none applies.; title: string (必填) — Short human-readable summary (the HTTP reason phrase for 'about:blank').; status.toString: (radix?: number) => string (必填) — Returns a string representation of an object.; status.toFixed: (fractionDigits?: number) => string (必填) — Returns a string representing a number in fixed-point notation.; status.toExponential: (fractionDigits?: number) => string (必填) — Returns a string containing a number represented in exponential notation.; status.toPrecision: (precision?: number) => string (必填) — Returns a string containing a number represented either in exponential or fixed-point notation with a specified number of digits.; status.valueOf: () => number (必填) — Returns the primitive value of the specified object.; status.toLocaleString: { (locales?: string | string[], options?: Intl.NumberFormatOptions): string; (locales?: Intl.LocalesArgument, options?: Intl.NumberFormatOptions): string; } (必填) — Converts a number to a string by using the current or specified locale.; detail?: string (可选) — Human-readable explanation specific to this occurrence.

Compiler-recognized property decorator; inert no-op at runtime.

reflect: boolean (必填); attribute?: string | false (可选); type?: unknown (可选); converter?: unknown (可选)

Provide a plain protocol value; the provider Signal remains OE-private.

Read-only signal protocol used by computed values.

value: T (必填); subscribe: (fn: (value: T) => void) => Unsubscribe (必填); __@SIGNAL_BRAND@1852.valueOf: () => boolean (必填) — Returns the primitive value of the specified object.

Server-render one compiled element through canonical Element composition.

Options for one `renderDsd()` call: the compiled component class to serialize, the values projected onto its compiled properties, optional route/source diagnostics metadata, the nested compiled tags the build admitted, and trusted parent-owned light children keyed by slot name.

componentClass?: CustomElementConstructor (可选); props?: Record<string, unknown> (可选); sourceInfo.route?: string (可选); sourceInfo.source?: string (可选); ssrRenderableTags?: readonly string[] (可选) — Build-admitted nested compiled tags. Omitted means shell-only rendering.; projectedChildren?: ReadonlyMap<string, TrustedHtml> (可选) — Trusted parent-owned light children keyed by slot name.

Recoverable render-phase error carrying the failing component path and tag.

The public result of one `renderDsd()` call: the serialized DSD `html`, the render errors collected while composing it (empty on success), the render metrics for the root component, and the hydration hints the client scheduler reads to upgrade islands.

html: string (必填); errors: RenderError[] (必填); metrics: DsdRenderMetrics (必填); hydrationHints: HydrationHint[] (必填)

Report an {@linkcode OpenElementError} to the telemetry hook, or console.error when none is installed.

code: string (必填); severity: ErrorSeverity (必填); phase: ErrorPhase (必填); recoverable: boolean (必填); statusCode.toString: (radix?: number) => string (必填) — Returns a string representation of an object.; statusCode.toFixed: (fractionDigits?: number) => string (必填) — Returns a string representing a number in fixed-point notation.; statusCode.toExponential: (fractionDigits?: number) => string (必填) — Returns a string containing a number represented in exponential notation.; statusCode.toPrecision: (precision?: number) => string (必填) — Returns a string containing a number represented either in exponential or fixed-point notation with a specified number of digits.; statusCode.valueOf: () => number (必填) — Returns the primitive value of the specified object.; statusCode.toLocaleString: { (locales?: string | string[], options?: Intl.NumberFormatOptions): string; (locales?: Intl.LocalesArgument, options?: Intl.NumberFormatOptions): string; } (必填) — Converts a number to a string by using the current or specified locale.; toJSON: () => Record<string, unknown> (必填); name: string (必填); message: string (必填); stack?: string (可选); cause?: unknown (可选)

One route admitted by the scanner: URL `path`, source `filePath`, the route `type`, the generated variable name (`varName`) the entry binds it to, and the optional registration tag. {@link RouteEntry.definePage} and {@link RouteEntry.hasEnhancedForms} carry the two source-derived admission facts the generated entries branch on.

path: string (必填); filePath: string (必填); type: "page" | "api" | "island" | "special" (必填); varName: string (必填); tagName?: string (可选); definePage?: boolean (可选) — True when the route module's default export is a definePage() definition (0.42.0-alpha.17, #960 — registration decoupling). The generated entry registers the page class under the path-derived fallback tag and IGNORES the tagName export for registration: on a definePage route the export only names a content element. Plain element routes keep tagName as their registration tag.; source?: string (可选) — Source text captured during scanning when includeSource is enabled.; hasEnhancedForms?: boolean (可选) — True when the page route source carries data-open-enhance (0.42.0-alpha.5, #569): the client entry must ship the form-enhancement layer even when the app has zero islands.; special?: SpecialFileType (可选); params?: string[] (可选)

Canonical request-time/SSG server route context.

request: Request (必填); params: Record<string, string> (必填); env: Env (必填); platform: Platform (必填); responseHeaders: Headers (必填) — Mutable response-only channel merged into the framework response.; route: Route (必填)

Context passed to a request-time ('dynamic') route loader. This is the server contract: the loader runs on the server with the Web-standard request, matched route params, the host environment and the platform object, and signals validation failure via fail()/redirect().

path: string (必填); filePath: string (必填)

Install the process-wide error telemetry hook (replaceable for tests, HMR, multi-app pages).

Create a writable signal through the selected signal engine.

Alias for APIs that accept either writable or read-only signals.

Special file kinds the route scanner recognizes by filename: `renderer` and `middleware`.

The build's admission verdict for one discovered tag: where the declaration lives (`modulePath`), how it was discovered (`source`), which render path it is admitted to, and the reason recorded for the manifest.

tagName: string (必填); modulePath: string (必填) — Module path of the island declaration. Empty for 'foreign' decisions: a foreign tag is consumed in JSX but declares no module the build owns.; source: "local" | "package" | "nested" | "foreign" (必填) — 'foreign' (#979, 0.43.0-alpha.2): a third-party WC tag discovered by the foreign-tag scanner in page/island JSX — recorded for visibility only; SSR still treats it as an opaque passthrough (renderPath 'client-only').; renderPath: "ssr+client" | "client-only" | "rejected" (必填); reason: string (必填)

Tags a deferred frame cannot safely install into an owned Part range: the browser installer rejects any frame whose markup carries one of these.

Schemes that make a URL attribute unsafe in a streamed frame.

URL-carrying attributes the frame check screens for script-bearing scheme obfuscation; only these attribute names are value-screened.

Control characters at or below this code point are stripped before the URL-scheme test, so tab/newline/control obfuscation cannot smuggle a scheme past admission.

Cross-realm StyleSheet constructor: the native CSSStyleSheet or the internal shim.

Minimal stylesheet contract (replaceSync + cssRules) satisfied by native and shim sheets.

replaceSync: (text: string) => void (必填); cssRules: StyleSheetRule[] (必填)

Mark an HTML string as trusted for explicit `innerHTML` sinks (the trust does not serialize).

Opaque capability marking HTML the application has explicitly vetted as trusted.

html: string (必填)

Whether a static attribute (name/value as authored into the Part Program) makes a streamed frame unsafely installable: event-handler, seed-spoofing, and srcdoc names fail outright, and URL-carrying names fail when the entity-decoded, control-stripped value carries a script scheme.

Wrap rendered HTML in a full HTML document. Adds DOCTYPE, head (title, meta, preload), and body. Supports CSP nonce and dev scripts (e.g. Vite client, route module registration).

Parse one module source and report the semantic facts the compiler boundary and the Vite graph adapters branch on. Pure: it never resolves imports from disk and never throws on foreign or invalid syntax — an unparsable module simply yields no recognized facts.

The authored substring every compiled element module contains (`@element(`), used as the cheap prefilter.

Error shape consumed by the Vite plugin and compiler tests.

The `open:compiled-element` Vite plugin: runs at `enforce: 'pre'` so the compiler sees authored TSX before Vite's own TS/JSX lowering, compiles every module with a canonically bound `@element` decorator, and leaves all other modules untouched. `workspaceRoot` anchors generated source-map ids for linked workspace packages.

workspaceRoot?: string (可选) — Workspace root used as the second identity anchor: Vite ids outside the project root are typically linked workspace packages, and anchoring them on the workspace keeps machine paths out of emitted source maps. Callers that do not know a workspace root omit it and get ids passed through.; typeCheckEmitted?: boolean (可选) — Type-check every module the compiler emits and fail the build when one does not compile (#1386 item 2). Off by default: it runs a TypeScript program per emitted module, which a dev-server transform must not pay. A build or verification pass turns it on, so the emitted program is checked against the declarations the consumer compiles against.; resolutionPaths?: Record<string, string[]> (可选) — Specifier → candidate files map used when `typeCheckEmitted` is on.

Compile one opted-in module without binding the caller to Vite. The core adapter hook and the inline SSR/client builds all use this same function, which prevents duplicate compiler implementations from drifting. Returns null for modules without a canonically bound

Compile one authored TSX module into the compiled Part Program module. `fileName` is used for diagnostics and the emitted source map only — filesystem resolution is the caller's job. Fails closed with a {@link CompiledElementError} carrying the ordered OEC diagnostics.

The compiled module the transform emits for one authored TSX source: the generated `code`, its Source Map v3, the Part Program facts the runtime consumes, and the ordered diagnostics that did not fail the compile.

code: string (必填); map: CompiledElementSourceMap (必填) — Real Source Map v3 for the emitted module (VLQ line+column segments derived from the compiler's span records and emission provenance). The same map is embedded as the module's inline map; the Vite shell returns it as its `map` output for downstream composition (#1210).; program: PartProgramV1 (必填)

A source-aware compiler diagnostic: stable OEC code, message and source range.

code: string (必填); message: string (必填); file: string (必填); line.toString: (radix?: number) => string (必填) — Returns a string representation of an object.; line.toFixed: (fractionDigits?: number) => string (必填) — Returns a string representing a number in fixed-point notation.; line.toExponential: (fractionDigits?: number) => string (必填) — Returns a string containing a number represented in exponential notation.; line.toPrecision: (precision?: number) => string (必填) — Returns a string containing a number represented either in exponential or fixed-point notation with a specified number of digits.; line.valueOf: () => number (必填) — Returns the primitive value of the specified object.; line.toLocaleString: { (locales?: string | string[], options?: Intl.NumberFormatOptions): string; (locales?: Intl.LocalesArgument, options?: Intl.NumberFormatOptions): string; } (必填) — Converts a number to a string by using the current or specified locale.; character: number (必填); start: number (必填); end: number (必填)

One diagnostic the type checker produced for the emitted module. `file` is the virtual module id the check was given; the remaining fields locate the range inside the EMITTED text.

code.toString: (radix?: number) => string (必填) — Returns a string representation of an object.; code.toFixed: (fractionDigits?: number) => string (必填) — Returns a string representing a number in fixed-point notation.; code.toExponential: (fractionDigits?: number) => string (必填) — Returns a string containing a number represented in exponential notation.; code.toPrecision: (precision?: number) => string (必填) — Returns a string containing a number represented either in exponential or fixed-point notation with a specified number of digits.; code.valueOf: () => number (必填) — Returns the primitive value of the specified object.; code.toLocaleString: { (locales?: string | string[], options?: Intl.NumberFormatOptions): string; (locales?: Intl.LocalesArgument, options?: Intl.NumberFormatOptions): string; } (必填) — Converts a number to a string by using the current or specified locale.; message: string (必填); file: string (必填); line: number (必填); character: number (必填)

How the emitted module's imports resolve, and any virtual files to add.

paths?: Record<string, string[]> (可选) — Module resolution map for the specifiers the emitted module imports, in TypeScript `paths` form (specifier → candidate files). A caller that resolves `@openelement/element` through the workspace passes that map; omitting it means imported specifiers resolve through `node_modules`, which is what a packed consumer has instead.; compilerOptions?: ts.CompilerOptions (可选) — Extra compiler options, merged over the defaults below.; extraFiles?: Readonly<Record<string, string>> (可选) — Support files the emitted module imports, supplied as text for ids that do not exist on disk (a bundler's other virtual modules). The emitted module itself is added under `fileName`.

`true` when the emitted module type-checks. The boolean form exists so a caller that only needs a verdict does not destructure an empty array; the diagnostics form is for callers that must report what failed.

Precise second stage behind the substring prefilter: a canonically bound `@element(...)` decorator application on a class declaration (provenance decided by the semantic core's intrinsic-binding model). Modules that only mention the marker in a string literal or comment, or spell it through a foreign/local binding, do not reach the compiler.

Cheap first stage only — NOT a recognizer. The substring match exists to keep plain modules off the AST path and may false-positive (string literals and comments match); it may also false-negative on namespace-qualified spellings (`@ns.element(...)`), which are unsupported by the grammar anyway (#1209). Binding provenance and admission are decided exclusively by the semantic core.

The bundler-neutral facts one module source yields: its relative imports, the intrinsic bindings it admits ({@link ModuleSemanticFacts.compiledElementDecorator}, {@link ModuleSemanticFacts.exportedTagName}, custom-element tags it defines or references) and the interaction-event names its handlers bind. The Vite graph adapter branches on these without re-parsing the AST.

relativeImports: string[] (必填); compiledElementDecorator: boolean (必填); unsupportedElementDecorator?: string (可选) — Set when a class decorator spells the `element` intrinsic through unsupported or ambiguous provenance (type-only import, namespace access, default import, conflicting duplicate bindings, or a relative-module re-export). Never set for clearly foreign bindings (third-party packages, local declarations, bare/global spellings) — those modules are simply not OpenElement modules. The plugin gate compil…; exportedTagName?: string (可选); definePage: boolean (必填); usesExportedTagName: boolean (必填); enhancedForm: boolean (必填); defaultCompiledTag?: string (可选); definedCustomElementTags: string[] (必填); referencedCustomElementTags: string[] (必填); compilerInteractionEvents: string[] (必填)

Compile-time source identity for a module: absolute Vite ids are converted to project-relative POSIX paths so Part Program `metadata.sourceFile` and `sourceMap.file` never embed the build machine's path. Module resolution, diagnostics, and HMR keys keep using the caller's own id. Anchors are explicit, never guessed from path substrings (a checkout living under e.g. `/srv/www/` must not fool the cut): the Vite project root first, then the workspace root when the caller knows it (a module outside the project root is typically a linked workspace package). Callers that hand the compiler a path outside every known root (synthetic ids, non-Deno projects without a Vite root) get the id back unchanged — there is no correct relative form to invent, and the library boundary must not reject paths it cannot anchor. This module stays runtime-neutral: resolving a workspace root from disk is the caller's job.

Strip the inline map comment from a compiled module at the Vite boundary. The core artifact embeds its real Source Map v3 inline for standalone consumers; the Vite transform returns that same map as its `map` output so Vite composes it with the rest of the pipeline — leaving the comment in the served code would create a second, conflicting map story (#1210).

Type-check one emitted compiled module. Returns `[]` when the module type-checks; otherwise every diagnostic the checker reported, in emission order, so a build can print all of them instead of only the first. The `fileName` should be the module's real (virtual) id, not a placeholder: module resolution and `paths` matching both key off it, and the diagnostics quote it back.

Validate an unknown value as a Part Program v1. The validator is intentionally strict: unknown instruction kinds, missing ownership records and unsafe paths fail before a runtime can guess at their meaning.

Escape an HTML attribute value. Delegates to `escapeHtml` so both share the single `ESCAPE_MAP` and the same single-pass replacement (consolidated in v0.42.0-alpha.9, #633). Empty-value conventions remain intentionally distinct by design: - `escapeHtml` returns '' for non-string input. - `escapeAttrValue` (below) coerces via `String()` and is the boundary meant for unknown/variable attribute values.

Escape a string for use as an attribute value (double-quoted)

Escape the five HTML-significant characters in text content.

Branded type: a string that has been HTML-escaped (safe for text content)

Mark an HTML string as trusted for explicit `innerHTML` sinks (the trust does not serialize).

Opaque capability marking HTML the application has explicitly vetted as trusted.

html: string (必填)

Branded type: a string that is intentionally raw/untrusted HTML

Wrap rendered HTML in a full HTML document. Adds DOCTYPE, head (title, meta, preload), and body. Supports CSP nonce and dev scripts (e.g. Vite client, route module registration).

Typechecking-only fragment marker; fails closed when executed at runtime.

JSX type interface consumed by TypeScript's automatic JSX transform.

Typechecking-only factory; fails closed when executed at runtime.

Typechecking-only fragment marker; fails closed when executed at runtime.

Typechecking-only factory; fails closed when executed at runtime.

JSX type interface consumed by TypeScript's automatic JSX transform.

Typechecking-only factory; fails closed when executed at runtime.

Create a {@link Logger} that prefixes every message with `[tag]`.

Create a fresh, empty warning scope for one render.

logger.ts - Tagged console logger. Lightweight scoped logger. Returns plain functions so it is tree-shakable and has zero class overhead.

debug: (msg: string, ...args: unknown[]) => void (必填); info: (msg: string, ...args: unknown[]) => void (必填); warn: (msg: string, ...args: unknown[]) => void (必填); error: (msg: string, ...args: unknown[]) => void (必填)

Warn at most once per `key` for the given render {@link WarnScope}, falling back to a process-wide set when no scope is passed.

A render-scoped warning tracker. Pass a fresh `WarnScope` (via `createWarnScope()`) into `warnOnce` at a render entry (e.g. once per SSR document in `wrapInDocument`). This keeps a given key from being suppressed for the entire process: the next page/request gets a new scope and the warning can fire again. This fixes the previous behavior where `warnOnce` permanently muted a key across all requests/SSG pages (v0.42.0-alpha.9, #643).

warned: Set<string> (必填)

The `open:compiled-element` Vite plugin: runs at `enforce: 'pre'` so the compiler sees authored TSX before Vite's own TS/JSX lowering, compiles every module with a canonically bound `@element` decorator, and leaves all other modules untouched. `workspaceRoot` anchors generated source-map ids for linked workspace packages.

workspaceRoot?: string (可选) — Workspace root used as the second identity anchor: Vite ids outside the project root are typically linked workspace packages, and anchoring them on the workspace keeps machine paths out of emitted source maps. Callers that do not know a workspace root omit it and get ids passed through.; typeCheckEmitted?: boolean (可选) — Type-check every module the compiler emits and fail the build when one does not compile (#1386 item 2). Off by default: it runs a TypeScript program per emitted module, which a dev-server transform must not pay. A build or verification pass turns it on, so the emitted program is checked against the declarations the consumer compiles against.; resolutionPaths?: Record<string, string[]> (可选) — Specifier → candidate files map used when `typeCheckEmitted` is on.

Route action: handles form submissions for a page route.

Request header selecting the action response channel: `true` marks a programmatic caller and selects the serialized ActionResult union; `enhance` marks the built-in morph enhancement and selects the same full-HTML responses the no-JS path receives.

Context passed to a route action function (extends loader context).

formData: FormData (必填); request: Request (必填); params: Record<string, string> (必填); env: Env (必填); platform: Platform (必填); responseHeaders: Headers (必填) — Mutable response-only channel merged into the framework response.; route: Route (必填)

The discriminated result an action returns: `success` carries the action's data; `failure` carries an HTTP status and payload. See `ActionResult` for the canonical classifier that produces it.

Wire shape returned to the JavaScript form-enhancement path (0.42.0-alpha.2). The no-JS path never sees this: it gets the equivalent semantics as plain HTTP (303 on success, 422 with the re-rendered form on validation failure, redirect/error as status codes). Error outcomes (CSRF 403, unknown action 404, unparseable body 400, unexpected 500) are NOT part of this union: since 0.42.0-alpha.13 (#863) they answer RFC 9457 Problem Details with the PROBLEM_JSON_MEDIA_TYPE content type — see ProblemDetails.

Canonical application-level classification for an action return value. Hono and SPA executors project this result differently, but neither may redefine validation failure or admit a raw Response as action data.

Convention path for the auto-registered application shell.

Convention-relative suffix of the auto-registered application shell.

The tag name the convention shell is registered under.

Default convention base: the directory the tokens/app-shell/data conventions resolve under when `dirs` is omitted (or has no shared leading segment).

Default component directory (`app/components`), the `dirs.components` default.

Convention path for the structural document-head module (`app/head.tsx`).

Convention-relative suffix of the structural document-head module.

Default island directory (`app/islands`), the `dirs.islands` default.

The site-title convention source (the package.json `name` field).

Default route directory (`app/routes`), the `dirs.routes` default.

Convention-relative suffix of the design-token stylesheet.

Convention path for the design-token stylesheet.

The app-shell convention path for a resolved `dirs` block.

The structural document-head convention path for a resolved `dirs` block.

The token stylesheet convention path for a resolved `dirs` block.

Build the canonical OpenElement request context from a platform request event.

request: Request (必填); params?: Record<string, string> (可选); env?: Env (可选); platform?: unknown (可选)

Inputs for building an {@linkcode OpenElementRequestContext} from a platform request event.

request: Request (必填); params?: Record<string, string> (可选); env?: Env (可选); platform?: unknown (可选)

`defineConfig()` — identity helper that pins the config file's shape.

renderer?: "native" | "lit" (可选) — Page renderer. Omit to keep the compiled native renderer.; dirs.routes?: string (可选) — Route directory. Defaults to `app/routes`.; dirs.islands?: string (可选) — Island directory. Defaults to `app/islands`.; dirs.components?: string (可选) — Component directory. Defaults to `app/components`.; appShell?: false | { import: string; props?: Record<string, unknown>; } (可选) — Application shell. `false` opts out of the `app-shell.tsx` convention; an object registers the named module. `tagName` is derived from the import's basename, so it is not part of the surface.; packageIslands?: string[] (可选) — Extra package names whose island modules the build admits (e.g. `['@openelement/ui']`). The loader folds this list into the SSR externalization list the bundler needs, so a package listed here is bundled rather than imported at run time; there is no separate `ssr.noExternal` key.; head.title?: string (可选) — Document title; defaults to the package.json `name`.; head.description?: string (可选) — `<meta name="description">` + `og:description`.; head.lang?: string (可选) — `<html lang>`; defaults to `en`.; head.favicon?: string (可选) — Site-root-relative favicon path, emitted as `<link rel="icon">`.; head.ogImage?: string (可选) — `og:image` URL. Absolute (crawlable) or site-root-relative.; head.stylesheets?: string[] (可选) — External stylesheets linked into `<head>`.; head.scripts?: OpenElementHeadScript[] (可选) — External scripts emitted into `<head>`; inline code is not accepted here.; styles.tokens?: string (可选) — Token stylesheet path; defaults to the `styles/tokens.css` convention.; i18n?: OpenElementI18nConfig (可选) — Locale-prefixed build configuration.; viewTransition?: boolean (可选) — Client-navigation View Transitions. Boolean for now; an object form (per-transition types) is a possible future widening of this key.; speculation?: boolean (可选) — Speculation Rules emission. Boolean for now: `true` uses the framework route-derived defaults, `false` emits none. An object form (explicit prerender/prefetch lists, exclusions, eagerness) is a possible future widening of this key.; build.manifestBudget?: Record<string, number> (可选) — Advisory per-entry manifest budgets in KB, e.g. `{ islandKB: 100, totalJsKB: 300 }`.; middleware.corsOrigin?: string | string[] (可选) — CORS allowlist; omitted means localhost-only reflection (production warning).

Validate and register an island delivery descriptor; returns the normalized config.

ssr?: boolean (可选); dsd?: boolean (可选); hydrate?: IslandDeliveryStrategy (可选) — Hydration strategy — same values as `IslandOptions.hydrate` on the element package (`the element/src/internal/protocol/island.ts`): 'load' | 'idle' | 'visible' | 'media' | 'only'.; media?: string (可选) — Media query required by the `media` delivery strategy.; tags?: readonly string[] (可选) — Custom-element tags delivered by this one capability module.; tagNames?: readonly string[] (可选) — Alias accepted by generated artifact producers.; exportNames?: Readonly<Record<string, string>> (可选) — Named constructor exports keyed by delivered custom-element tag.

Attach a page descriptor to a compiled page element class. Canonical 0.44 page authoring: the route module default-exports the compiled class (produced by the open:compiled-element transform) wrapped in definePage(). The descriptor holds head/route/renderIntent metadata plus the optional props/error projectors; it must NOT create classes or hold a render function — the compiled class's Part Program is the render. import { definePage } from '@openelement/router'; import { HomePage } from '../components/page-home.tsx'; export const loader = async (ctx) => ({ ... }); // module named exports export default definePage(HomePage, { head: { title: 'Home' }, props: ({ data }) => ({ heading: data?.heading ?? '' }), });

Return a structured action failure with an HTTP status and typed data payload.

toString: (radix?: number) => string (必填) — Returns a string representation of an object.; toFixed: (fractionDigits?: number) => string (必填) — Returns a string representing a number in fixed-point notation.; toExponential: (fractionDigits?: number) => string (必填) — Returns a string containing a number represented in exponential notation.; toPrecision: (precision?: number) => string (必填) — Returns a string containing a number represented either in exponential or fixed-point notation with a specified number of digits.; valueOf: () => number (必填) — Returns the primitive value of the specified object.; toLocaleString: { (locales?: string | string[], options?: Intl.NumberFormatOptions): string; (locales?: Intl.LocalesArgument, options?: Intl.NumberFormatOptions): string; } (必填) — Converts a number to a string by using the current or specified locale.

Type guard for {@linkcode OpenElementActionFailure}, including its duck-typed cross-realm shape.

Per-island delivery configuration (SSR/DSD participation and hydration strategy).

ssr?: boolean (可选); dsd?: boolean (可选); hydrate?: IslandDeliveryStrategy (可选) — Hydration strategy — same values as `IslandOptions.hydrate` on the element package (`the element/src/internal/protocol/island.ts`): 'load' | 'idle' | 'visible' | 'media' | 'only'.; media?: string (可选) — Media query required by the `media` delivery strategy.; tags?: readonly string[] (可选) — Custom-element tags delivered by this one capability module.; tagNames?: readonly string[] (可选) — Alias accepted by generated artifact producers.; exportNames?: Readonly<Record<string, string>> (可选) — Named constructor exports keyed by delivered custom-element tag.

Delivery strategy for an island: a hydration trigger or media-gated loading.

Type guard for {@linkcode OpenElementNotFound}, including its duck-typed cross-realm shape.

Type guard for {@linkcode OpenElementRedirect}, including its duck-typed cross-realm shape.

A JSON value: the complete set of shapes the structured-data channel admits (JSON primitives, arrays and plain objects, all readonly). Functions, `undefined`, bigint, symbols, class instances, Date, Map and Set are rejected by the runtime normalizer and by this type, so an author cannot write a document the serializer would refuse.

Route loader: fetches data for a page route.

Context passed to a request-time ('dynamic') route loader.

request: Request (必填); params: Record<string, string> (必填); env: Env (必填); platform: Platform (必填); responseHeaders: Headers (必填) — Mutable response-only channel merged into the framework response.; route: Route (必填)

Throw an {@linkcode OpenElementNotFound} to render the 404 path.

Accepted keys inside `appShell`.

Accepted keys inside `build`.

Canonical config-file name, resolved in the project root.

The exact accepted key set, used by the fail-closed unknown-key check and by the error message (the message must name the accepted surface, never just reject). The nested arrays below are this module's single copy of the sub-key surfaces; the host-tooling loader imports them instead of restating them.

Accepted keys inside `dirs`.

Accepted keys inside `head`.

Keys of one `head.scripts` entry.

Head keys that carry a plain string value.

Accepted keys inside `i18n`.

Accepted keys inside `middleware`.

Accepted keys inside `styles`.

Expected-failure channel for actions (0.42.0-alpha.2, decision 0120): validation failures RETURN `fail(status, data)` — never throw — so the server can answer 422 with the form re-rendered and the submitted values echoed back. Thrown values keep the exception channel (redirect/notFound/error page).

Build-output switches.

manifestBudget?: Record<string, number> (可选) — Advisory per-entry manifest budgets in KB, e.g. `{ islandKB: 100, totalJsKB: 300 }`.

Source roots; see the `dirs` section of the module doc comment.

routes?: string (可选) — Route directory. Defaults to `app/routes`.; islands?: string (可选) — Island directory. Defaults to `app/islands`.; components?: string (可选) — Component directory. Defaults to `app/components`.

The document-head channel. Structured only: every entry serializes through the framework's URL/attribute validators, so a raw HTML string has no way in. Structural head content that is not expressible here (font preloads, icons, feed links, inline CSS) belongs in the `app/head.tsx` convention instead.

title?: string (可选) — Document title; defaults to the package.json `name`.; description?: string (可选) — `<meta name="description">` + `og:description`.; lang?: string (可选) — `<html lang>`; defaults to `en`.; favicon?: string (可选) — Site-root-relative favicon path, emitted as `<link rel="icon">`.; ogImage?: string (可选) — `og:image` URL. Absolute (crawlable) or site-root-relative.; stylesheets?: string[] (可选) — External stylesheets linked into `<head>`.; scripts?: OpenElementHeadScript[] (可选) — External scripts emitted into `<head>`; inline code is not accepted here.

One structured `<script src>` descriptor accepted by `head.scripts`.

src: string (必填) — Script URL: absolute, or site-root relative (`/prism-init.js`).; defer?: boolean (可选) — Emit `defer`; leave unset for a parser-blocking external script.; crossOrigin?: string (可选) — `crossorigin` attribute value, e.g. `anonymous`.; integrity?: string (可选) — Subresource-integrity digest for the script.

Locale configuration for a locale-prefixed build.

locales: string[] (必填) — Every locale the build emits, default locale included.; defaultLocale: string (必填) — The locale served at the unprefixed root.

Not-found signal thrown from a loader to render the route's 404 path.

The page descriptor the pipeline reads (`module.default.openElementPage`). Attached to the compiled page class by definePage(); the class owns the render program, so the descriptor carries metadata and projectors only.

kind: "page" (必填); route.id?: string (可选); route.params?: readonly string[] (可选); route.layout?: string | false (可选) — Named layout selection (decision 0123): a string picks one of the `openElement({ layouts })` entries by name (unknown names fall back to the default shell); `false` renders the page without any app shell. Unset means the default shell.; head?: PageHead | PageHeadResolver<Data, Params> (可选); renderIntent: NormalizedPageRenderIntent (必填); props?: PagePropsProjector<Data, Params> (可选); error?: PageErrorProjector<Data, Params> (可选)

Redirect signal thrown from a loader/action to short-circuit rendering with an HTTP redirect.

Host-agnostic request context shared by App request adapters.

request: Request (必填); url: URL (必填); path: string (必填); method: string (必填); params: Record<string, string> (必填); searchParams: URLSearchParams (必填); env?: Env (可选); platform?: unknown (可选)

Overrides accepted by an `openelement.config.ts` file (unknown keys fail closed).

renderer?: "native" | "lit" (可选) — Page renderer. Omit to keep the compiled native renderer.; dirs.routes?: string (可选) — Route directory. Defaults to `app/routes`.; dirs.islands?: string (可选) — Island directory. Defaults to `app/islands`.; dirs.components?: string (可选) — Component directory. Defaults to `app/components`.; appShell?: false | { import: string; props?: Record<string, unknown>; } (可选) — Application shell. `false` opts out of the `app-shell.tsx` convention; an object registers the named module. `tagName` is derived from the import's basename, so it is not part of the surface.; packageIslands?: string[] (可选) — Extra package names whose island modules the build admits (e.g. `['@openelement/ui']`). The loader folds this list into the SSR externalization list the bundler needs, so a package listed here is bundled rather than imported at run time; there is no separate `ssr.noExternal` key.; head.title?: string (可选) — Document title; defaults to the package.json `name`.; head.description?: string (可选) — `<meta name="description">` + `og:description`.; head.lang?: string (可选) — `<html lang>`; defaults to `en`.; head.favicon?: string (可选) — Site-root-relative favicon path, emitted as `<link rel="icon">`.; head.ogImage?: string (可选) — `og:image` URL. Absolute (crawlable) or site-root-relative.; head.stylesheets?: string[] (可选) — External stylesheets linked into `<head>`.; head.scripts?: OpenElementHeadScript[] (可选) — External scripts emitted into `<head>`; inline code is not accepted here.; styles.tokens?: string (可选) — Token stylesheet path; defaults to the `styles/tokens.css` convention.; i18n?: OpenElementI18nConfig (可选) — Locale-prefixed build configuration.; viewTransition?: boolean (可选) — Client-navigation View Transitions. Boolean for now; an object form (per-transition types) is a possible future widening of this key.; speculation?: boolean (可选) — Speculation Rules emission. Boolean for now: `true` uses the framework route-derived defaults, `false` emits none. An object form (explicit prerender/prefetch lists, exclusions, eagerness) is a possible future widening of this key.; build.manifestBudget?: Record<string, number> (可选) — Advisory per-entry manifest budgets in KB, e.g. `{ islandKB: 100, totalJsKB: 300 }`.; middleware.corsOrigin?: string | string[] (可选) — CORS allowlist; omitted means localhost-only reflection (production warning).

A compiled element class carrying the page descriptor static.

Maps a caught render/loader/action failure onto the error variant of the page's compiled properties. Its presence declares that the page's compiled markup carries an error variant (the generated entry renders the page with these props and status 500 — the POST/GET error-boundary channel of decision 0121 §7); without it the generic status page answers.

Page <head> meaning declared by a route descriptor (v0.44, decision 0143; canonical/alternates added in Beta.2.2, #1326; structured data added in Beta.2.3). Either a static object or — via PageHeadResolver — resolved per render from the request-scoped context by resolvePageDocument (@openelement/router/document) before either serializer runs.

title?: string (可选); description?: string (可选); meta?: Record<string, string | number | boolean>[] (可选); canonical?: string (可选) — Canonical URL of this page (Beta.2.2, #1326), resolved into <link rel="canonical"> by the shared Document seam.; alternates?: { href: string; hreflang?: string; }[] (可选) — Locale alternates of this page (Beta.2.2, #1326), resolved into <link rel="alternate" hreflang="..."> entries in author order.; structuredData?: StructuredDataEntry[] (可选) — Structured data (JSON-LD) for this page, resolved into one `<script type="application/ld+json">` element per document in <head>. This is a DATA channel, not a markup channel: entries must be JSON data, and resolvePageDocument fails closed on anything JSON cannot represent (functions, undefined, non-finite numbers, non-plain objects, cycles). It is deliberately NOT reachable through `dangerouslyHe…; dangerouslyHeadFragments?: string[] (可选)

Resolves a page's head from the request-scoped context (Beta.2.2, #1326). The resolver receives the same context object the props projector gets and must stay a pure function of it — the Document seam (@openelement/router/ document) never fetches, caches, or schedules loaders on its own.

The request-scoped context handed to a page's props projector. Everything a compiled page can render must pass through here: the compiled render() only reads `this.<property>`, so the projector is the single deterministic seam that maps loader data, action data, params and request onto the page's compiled properties (v0.44, decision 0143).

data: Data (必填); actionData: unknown (必填); params: Params (必填); request?: Request (可选); locale?: string (可选) — Resolved application locale for this render, when i18n is configured.; route.path?: string (可选); route.filePath?: string (可选); meta: PageMeta (必填)

Maps the request-scoped context onto the page's compiled properties. Declared as part of the page descriptor; the generated server entry and the SPA bootstrap call it per render and feed the result to renderDsd() props (server) or pre-connect property sets (SPA).

Media type of the RFC 9457 action error channel (#863).

RFC 9457 Problem Details document (0.42.0-alpha.13, #863): the action error channel answers `application/problem+json` instead of the bespoke `{ type: 'error', error: { message } }` JSON, so HTTP tooling recognizes failures natively. With `type: 'about:blank'`, `title` is the HTTP reason phrase and `detail` carries the specific explanation. The wire shape is alpha-unfrozen; the 1.0 acceptance freezes it in this problem+json form.

type: string (必填) — URI reference identifying the problem type; 'about:blank' when none applies.; title: string (必填) — Short human-readable summary (the HTTP reason phrase for 'about:blank').; status.toString: (radix?: number) => string (必填) — Returns a string representation of an object.; status.toFixed: (fractionDigits?: number) => string (必填) — Returns a string representing a number in fixed-point notation.; status.toExponential: (fractionDigits?: number) => string (必填) — Returns a string containing a number represented in exponential notation.; status.toPrecision: (precision?: number) => string (必填) — Returns a string containing a number represented either in exponential or fixed-point notation with a specified number of digits.; status.valueOf: () => number (必填) — Returns the primitive value of the specified object.; status.toLocaleString: { (locales?: string | string[], options?: Intl.NumberFormatOptions): string; (locales?: Intl.LocalesArgument, options?: Intl.NumberFormatOptions): string; } (必填) — Converts a number to a string by using the current or specified locale.; detail?: string (可选) — Human-readable explanation specific to this occurrence.

Default request-to-props projection used when a page descriptor declares no props projector: route params first, then loader-data record entries. The compiled serializer consumes only the page's declared compiled properties, so extra entries are ignored. Shared by the generated server entries and the SPA bootstrap (each carries its own copy — generated code cannot import this module's internals). Dangerous keys are filtered through the canonical isDangerousKey predicate (#1214): a hostile loader payload such as JSON.parse('{"__proto__": ...}') can never re-prototype the projection record or the page host it is projected onto. The generated server runtime enforces the same rule with a serialized copy of the canonical DANGEROUS_KEYS list.

params?: Record<string, string> (可选); data?: unknown (可选)

Throw an {@linkcode OpenElementRedirect} for `location` (status must be a real 3xx).

hash: string (必填) — The **`hash`** property of the URL interface is a string containing a "#" followed by the fragment identifier of the URL. If the URL does not have a fragment identifier, this property contains an empty string, "". [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/hash); host: string (必填) — The **`host`** property of the URL interface is a string containing the host, which is the hostname, and then, if the port of the URL is nonempty, a ":", followed by the port of the URL. If the URL does not have a hostname, this property contains an empty string, "". [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/host); hostname: string (必填) — The **`hostname`** property of the URL interface is a string containing either the domain name or IP address of the URL. If the URL does not have a hostname, this property contains an empty string, "". IPv4 and IPv6 addresses are normalized, such as stripping leading zeros, and domain names are converted to IDN. [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/hostname); href: string (必填) — The **`href`** property of the URL interface is a string containing the whole URL. [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/href); toString: () => string (必填); origin: string (必填) — The **`origin`** read-only property of the URL interface returns a string containing the Unicode serialization of the origin of the represented URL. [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/origin); password: string (必填) — The **`password`** property of the URL interface is a string containing the password component of the URL. If the URL does not have a password, this property contains an empty string, "". [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/password); pathname: string (必填) — The **`pathname`** property of the URL interface represents a location in a hierarchical structure. It is a string constructed from a list of path segments, each of which is prefixed by a / character. [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/pathname); port: string (必填) — The **`port`** property of the URL interface is a string containing the port number of the URL. If the port is the default for the protocol (80 for ws: and http:, 443 for wss: and https:, and 21 for ftp:), this property contains an empty string, "". [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/port); protocol: string (必填) — The **`protocol`** property of the URL interface is a string containing the protocol or scheme of the URL, including the final ":". [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/protocol); search: string (必填) — The **`search`** property of the URL interface is a search string, also called a query string, that is a string containing a "?" followed by the parameters of the URL. If the URL does not have a search query, this property contains an empty string, "". [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/search); searchParams: URLSearchParams (必填) — The **`searchParams`** read-only property of the URL interface returns a URLSearchParams object allowing access to the GET decoded query arguments contained in the URL. [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/searchParams); username: string (必填) — The **`username`** property of the URL interface is a string containing the username component of the URL. If the URL does not have a username, this property contains an empty string, "". [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/username); toJSON: () => string (必填) — The **`toJSON()`** method of the URL interface returns a string containing a serialized version of the URL, although in practice it seems to have the same effect as URL.toString(). [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/toJSON)

Resolve `dirs` to the three absolute-in-project roots the scanner reads. Omitted entries take the documented defaults.

routes?: string (可选) — Route directory. Defaults to `app/routes`.; islands?: string (可选) — Island directory. Defaults to `app/islands`.; components?: string (可选) — Component directory. Defaults to `app/components`.

Canonical request-time/SSG server route context.

request: Request (必填); params: Record<string, string> (必填); env: Env (必填); platform: Platform (必填); responseHeaders: Headers (必填) — Mutable response-only channel merged into the framework response.; route: Route (必填)

Context passed to a request-time ('dynamic') route loader. This is the server contract: the loader runs on the server with the Web-standard request, matched route params, the host environment and the platform object, and signals validation failure via fail()/redirect().

path: string (必填); filePath: string (必填)

One structured-data document — a JSON-LD node such as a schema.org BlogPosting or WebSite. Its values are JSON data (string, finite number, boolean, null, array, plain object) and nothing else: the serializer emits the document as data, so an HTML string is not a document here.

One <link rel="alternate"> record, typically carrying an hreflang.

href: string (必填); hreflang?: string (可选)

A page's resolved document meaning: every <head> field after the head resolver (when the descriptor declares one) has run, plus the normalized `links` projection the serializers consume. Call-site precedence is resolved-document value first, route/build docConfig fallback second.

title?: string (可选); description?: string (可选); meta?: Record<string, string | number | boolean>[] (可选); structuredData?: StructuredDataEntry[] (可选) — Structured data (JSON-LD), one serialized `<script type= "application/ld+json">` element per entry. Normalized here to plain JSON data so the serializer only has to escape, never interpret.; dangerouslyHeadFragments?: string[] (可选); lang?: string (可选) — Document language: the resolved application locale for this render.; canonical?: string (可选); alternates?: PageHeadAlternate[] (可选); links: ResolvedDocumentLink[] (必填) — Canonical first, then alternates in author order — deterministic.

A normalized <link> the serializers emit into <head>.

rel: "canonical" | "alternate" (必填); href: string (必填); hreflang?: string (可选)

Resolves the descriptor head into the page's ResolvedDocument. A head may be a static object or a resolver receiving the same request-scoped context the props projector gets; resolver output is validated exactly like a static head so malformed page meaning fails loudly at either build time or request time instead of being silently dropped from the serialized document.

title?: string (可选); description?: string (可选); meta?: Record<string, string | number | boolean>[] (可选); canonical?: string (可选) — Canonical URL of this page (Beta.2.2, #1326), resolved into <link rel="canonical"> by the shared Document seam.; alternates?: { href: string; hreflang?: string; }[] (可选) — Locale alternates of this page (Beta.2.2, #1326), resolved into <link rel="alternate" hreflang="..."> entries in author order.; structuredData?: StructuredDataEntry[] (可选) — Structured data (JSON-LD) for this page, resolved into one `<script type="application/ld+json">` element per document in <head>. This is a DATA channel, not a markup channel: entries must be JSON data, and resolvePageDocument fails closed on anything JSON cannot represent (functions, undefined, non-finite numbers, non-plain objects, cycles). It is deliberately NOT reachable through `dangerouslyHe…; dangerouslyHeadFragments?: string[] (可选)

Mount after host middleware/routes; unmatched URLs continue to the host.

Dialect-free WinterCG route handler: return a Response to short-circuit, or `next()` to pass control down the method's handler chain; the last handler's `next` is the host middleware chain's own next.

Route-scoped request context handed to every {@link HttpHandler}.

params: Record<string, string> (必填); searchParams: URLSearchParams (必填); url: URL (必填)

A route record for the WinterCG middleware ({@link createRouteMiddleware}): the matching fields of a {@link RouteRecord} plus a per-method handler (or handler chain) map, so one path can answer each HTTP method differently.

handlers: Readonly<Record<string, HttpHandler | readonly HttpHandler[]>> (必填); path: string (必填); id?: string (可选); pattern.protocol?: string (可选); pattern.username?: string (可选); pattern.password?: string (可选); pattern.hostname?: string (可选); pattern.port?: string (可选); pattern.search?: string (可选); pattern.hash?: string (可选); pattern.baseURL?: string (可选)

Attach a page descriptor and host tag to a LitElement page class. import { defineLitPage } from '@openelement/router/lit'; import { NotesListPage } from '../components/notes-list-page.ts'; export const loader = async (ctx) => ({ ... }); export default defineLitPage('notes-list-page', NotesListPage, { renderIntent: { mode: 'dynamic' }, head: { title: 'Notes' }, props: ({ data }) => ({ notes: data?.notes ?? [] }), }); The class is rendered server-side by

A LitElement page class carrying the page descriptor and its host tag.

The page descriptor the pipeline reads (`module.default.openElementPage`). Attached to the compiled page class by definePage(); the class owns the render program, so the descriptor carries metadata and projectors only.

kind: "page" (必填); route.id?: string (可选); route.params?: readonly string[] (可选); route.layout?: string | false (可选) — Named layout selection (decision 0123): a string picks one of the `openElement({ layouts })` entries by name (unknown names fall back to the default shell); `false` renders the page without any app shell. Unset means the default shell.; head?: PageHead | PageHeadResolver<Data, Params> (可选); renderIntent: NormalizedPageRenderIntent (必填); props?: PagePropsProjector<Data, Params> (可选); error?: PageErrorProjector<Data, Params> (可选)

Render a registered LitElement page host to DSD HTML. Fails closed when the tag is invalid or no element class is registered for it in the SSR registry: the generated entry registers every page/island class explicitly before rendering, so an unregistered host is a pipeline bug, never a silent passthrough.

tag: string (必填); props?: Record<string, unknown> (可选)

Mounts an OpenElement request handler on a Nitro v3 route. Near pass-through: the event's standard `req` goes in, the handler's Response comes out — h3 v2 serves a returned Response as-is.

handler: OpenElementRequestHandler<Env> (必填); env?: Env (可选); platform?: unknown (可选); onBeforeRequestContext?: ((context: OpenElementRequestContext<Env>) => void | Promise<void>) (可选) — Observes the normalized OpenElement request context before the application handler runs. Route params are empty here unless the host supplies them on `event.context.params` before dispatch.

Minimal Nitro v3 route event shape (#857). Nitro v3 is fetch-native: its h3 v2 event carries `req`, a srvx ServerRequest that already IS a standard Request, so the pre-v3 method/path/headers/body translation layer is gone. The mount only wires the OpenElement runtime context around the standard Request → Response seam.

req: Request (必填); context.params?: Record<string, string> (可选); env?: Env (可选); platform?: unknown (可选)

Options for mounting an OpenElement request handler under a Nitro/Node server.

handler: OpenElementRequestHandler<Env> (必填); env?: Env (可选); platform?: unknown (可选); onBeforeRequestContext?: ((context: OpenElementRequestContext<Env>) => void | Promise<void>) (可选) — Observes the normalized OpenElement request context before the application handler runs. Route params are empty here unless the host supplies them on `event.context.params` before dispatch.

Convert the framework's Hono-style route dialect to WHATWG URLPattern syntax.

One URL matched against the table: the matched `route` record, the identity reported for it, the decoded path `params`, the parsed `searchParams`, and the raw URLPattern `patternResult` the match was derived from.

route: T (必填); id: string (必填); params: Record<string, string> (必填); searchParams: URLSearchParams (必填); patternResult: RoutePatternResult (必填)

One route as the table stores it: the pathname `path`, an optional stable `id` used in match results, optional non-pathname URL component patterns, and the admitted `methods`.

path: string (必填); id?: string (可选); pattern.protocol?: string (可选); pattern.username?: string (可选); pattern.password?: string (可选); pattern.hostname?: string (可选); pattern.port?: string (可选); pattern.search?: string (可选); pattern.hash?: string (可选); pattern.baseURL?: string (可选); methods?: readonly string[] (可选)

The table's verdict for one request: a `match` (with the resolved method), `method-not-allowed` (with the `allow` list the caller answers 405 with), or `not-found` when no path in the table matches at all.

Immutable route matcher built once from a route list: it freezes every record, rejects duplicate identities and pathname-owning patterns at construction, and answers {@link RouteTable.resolve} with a {@link RouteResolution}. `Pattern` is injectable so callers can pin the URLPattern implementation.

Construction options: a URL prefix every route is mounted under, and whether a trailing slash is significant.

basePath?: string (可选); trailingSlash?: "strict" | "ignore" (可选)

The matcher surface a client route list compiles to: matching, resolution and candidate count.

match: (input: string | URL, search?: string) => RouteMatch<RouteConfig> | null (必填); resolve: (input: string | URL, search?: string, method?: string) => RouteResolution<RouteConfig> (必填); candidateCount: (input: string | URL) => number (必填)

Compile a client route list into the canonical {@link RouteTable} matcher, with no router instance attached.

Create the client-side SPA router for `options.mode` over `options.routes`: it matches through the shared RouteTable, owns its navigation listeners and history/hash state, and reports every committed navigation through `onChange`.

mode: RouterMode (必填); routes: RouteConfig[] (必填); onChange?: (() => void | Promise<void>) (可选) — Called after navigation or browser history/hash changes update the current match.; onPending?: (() => void) (可选) — Invalidate pending execution as soon as a newer navigation owns intent.

Match a route through the canonical Alpha.9 RouteTable.

One client route: a {@link RouteRecord} plus the custom element `tagName` SPA mode instantiates for it and an optional `guard` that may veto the navigation by returning `false` or a redirect path.

tagName: string (必填) — Custom element tag to instantiate directly in SPA mode.; guard?: (() => Promise<boolean | string>) (可选); path: string (必填); id?: string (可选); pattern.protocol?: string (可选); pattern.username?: string (可选); pattern.password?: string (可选); pattern.hostname?: string (可选); pattern.port?: string (可选); pattern.search?: string (可选); pattern.hash?: string (可选); pattern.baseURL?: string (可选); methods?: readonly string[] (可选)

A live client router: the navigation entry points, the current match (`currentPath`/`currentRoute`/`params`/`searchParams`), and `dispose()` to release its listeners.

navigate: (path: string) => Promise<void> (必填); replace: (path: string) => Promise<void> (必填); dispose: () => void (必填); currentPath: string (必填); currentRoute: RouteConfig | null (必填); params: Record<string, string> (必填); searchParams: URLSearchParams (必填)

Navigation strategy: the History API ('history'), the URL hash ('hash'), or file-protocol auto-detection ('auto').

File size info for a single artifact

name: string (必填); path: string (必填); sizeBytes.toString: (radix?: number) => string (必填) — Returns a string representation of an object.; sizeBytes.toFixed: (fractionDigits?: number) => string (必填) — Returns a string representing a number in fixed-point notation.; sizeBytes.toExponential: (fractionDigits?: number) => string (必填) — Returns a string containing a number represented in exponential notation.; sizeBytes.toPrecision: (precision?: number) => string (必填) — Returns a string containing a number represented either in exponential or fixed-point notation with a specified number of digits.; sizeBytes.valueOf: () => number (必填) — Returns the primitive value of the specified object.; sizeBytes.toLocaleString: { (locales?: string | string[], options?: Intl.NumberFormatOptions): string; (locales?: Intl.LocalesArgument, options?: Intl.NumberFormatOptions): string; } (必填) — Converts a number to a string by using the current or specified locale.; sizeKB: string (必填)

Build an OpenElement application through the supported adapter boundary. Consumers configure the adapter in `vite.config.ts`; this function owns the invocation so CLI callers do not need to know the adapter's internal build phases or Vite plugin ordering.

Build the headExtras string from FrameworkOptions.inject. Serializes headFragments, stylesheets, and scripts into a single HTML string to inject into <head>. Validates all URLs and ensures no raw <script> tags bypass the structured injection APIs.

Full build manifest summary

phase: 1 | 2 | 3 (必填); timestamp: string (必填); islands: ArtifactInfo[] (必填); clientEntry: ArtifactInfo | null (必填); htmlPages: ArtifactInfo[] (必填); totalJsBytes.toString: (radix?: number) => string (必填) — Returns a string representation of an object.; totalJsBytes.toFixed: (fractionDigits?: number) => string (必填) — Returns a string representing a number in fixed-point notation.; totalJsBytes.toExponential: (fractionDigits?: number) => string (必填) — Returns a string containing a number represented in exponential notation.; totalJsBytes.toPrecision: (precision?: number) => string (必填) — Returns a string containing a number represented either in exponential or fixed-point notation with a specified number of digits.; totalJsBytes.valueOf: () => number (必填) — Returns the primitive value of the specified object.; totalJsBytes.toLocaleString: { (locales?: string | string[], options?: Intl.NumberFormatOptions): string; (locales?: Intl.LocalesArgument, options?: Intl.NumberFormatOptions): string; } (必填) — Converts a number to a string by using the current or specified locale.; totalHtmlBytes: number (必填); headExtrasSize: number (必填); warnings: string[] (必填) — Budget warnings (files > threshold)

Low-level Vite plugin pipeline: SSR dev server, SSG and islands without the content/i18n conveniences of `openElement()`.

mode?: "ssg" (可选) — Build/dev mode. 'ssg' (default) enables SSR dev server + static generation.; routes.dir?: string (可选); output.outDir?: string (可选); island.dir?: string (可选); island.upgradeStrategy?: string (可选); viewTransition?: boolean (可选); headExtras?: string (可选)

Adapter options extend Element options with build-only delivery declarations. The element package remains unaware of Vite/SSG policy.

Result of building head extras from FrameworkOptions.

headExtras: string (必填); allowHeadExtrasScripts: boolean (必填)

Vite plugin compiling `.mdx` route files into compiled page modules.

routesDir?: string (可选) — Routes directory (as configured in openElement()). The compiled page tag derives from the route-file-relative path so the generated entry's path-derived registration tag matches the program tag.

Create the full OpenElement Vite plugin set: route pipeline, SSG and islands.

head.title?: string (可选) — Document title; defaults to the package.json `name`.; head.description?: string (可选) — `<meta name="description">` + `og:description`.; head.lang?: string (可选) — `<html lang>`; defaults to `en`.; head.favicon?: string (可选) — Site-root-relative favicon path, emitted as `<link rel="icon">`.; head.ogImage?: string (可选) — `og:image` URL. Absolute (crawlable) or site-root-relative.; head.stylesheets?: string[] (可选) — External stylesheets linked into `<head>`.; head.scripts?: OpenElementHeadScript[] (可选) — External scripts emitted into `<head>`; inline code is not accepted here.; ssg.dynamicRouteFailure?: "fail" | "warn" (可选) — Policy for dynamic-route render failures during SSG. See {@link SsgRenderOptions.dynamicRouteFailure}.; build.outDir?: string (可选) — Output directory for the build artifacts. Defaults to `dist`.; build.manifestBudget?: { islandKB?: number; totalJsKB?: number; pageKB?: number; } (可选) — Advisory only: exceeded budgets print build-manifest warnings and never fail the build; enforce them in your own build-output test.; renderer?: "native" | "lit" (可选) — Page renderer selection (Beta.2.2, #1339). EXPLICIT, never inferred: 'native' (default) renders pages through the compiled Part Program serializer (renderDsd); 'lit' renders LitElement pages through; routesDir?: string (可选) — Directory the route scanner walks, relative to the Vite root. Defaults to `app/routes`.; islandsDir?: string (可选) — Directory island modules are discovered in. Defaults to `app/islands`.; componentsDir?: string (可选) — Directory non-route components live in. Defaults to `app/components`.; packageIslands?: string[] (可选) — Extra package names whose island modules the build admits, e.g. `['@openelement/ui']`.; appShell?: AppShellConfig (可选) — Application shell declaration; `false` disables the shell, `'default'` uses the built-in one.; layouts?: LayoutsConfig (可选) — Per-layout shell declarations keyed by layout name.; mode?: "ssg" (可选) — Build mode. 'ssg' (default) generates static HTML.; headExtras?: string (可选) — @dangerous injected as-is, only use with controlled content; inject.stylesheets?: (string | { href: string; integrity?: string; crossorigin?: "anonymous" | "use-credentials"; attrs?: Record<string, string | number | boolean>; })[] (可选) — Stylesheets linked into the document head; each entry is an href or a link record with integrity/crossorigin/attrs.; inject.scripts?: (string | { src: string; type?: string; async?: boolean; defer?: boolean; integrity?: string; crossorigin?: "anonymous" | "use-credentials"; attrs?: Record<str… (可选) — Scripts emitted into the document; each entry is a src or a script record with type/async/defer/integrity/crossorigin/attrs.; inject.headFragments?: string[] (可选) — @dangerous fragments injected as-is. Trust boundary (same level as `trustedHtml`): never concatenate user-controlled content into these fragments; sanitize untrusted data at your own system boundary first. The framework only enforces no-`<script>` and no-executable-`<style>`.; ssr.noExternal?: (string | RegExp)[] (可选); island.upgradeStrategy?: "load" | "idle" | "visible" | "only" (可选); viewTransition?: boolean (可选) — Enable the View Transitions API for client navigations. Defaults to true.; speculation?: boolean | { prerender?: string[]; prefetch?: string[]; exclude?: string[]; eagerness?: "immediate" | "moderate" | "conservative"; } (可选) — Speculation Rules emission: `true` uses framework defaults, or pass prerender/prefetch URL lists, exclusions and an eagerness.; middleware.cors?: boolean (可选) — Enable the built-in CORS middleware.; middleware.corsOrigin?: string | string[] (可选) — Static CORS allowlist data, serialized into the generated entry as JSON. Mutually exclusive with {@link FrameworkOptions.middleware.corsOriginModule }.; middleware.corsOriginModule?: string (可选) — Path to a module that default-exports `(origin: string) => string | undefined`. The generated entry imports the module — the callback is never serialized — so it may close over module scope and import dependencies. Resolved with the same idiom as `appShell.import` (e.g. './app/cors-origin.ts'). Mutually exclusive with `corsOrigin`.; middleware.requestId?: boolean (可选) — Emit and honor a per-request id header.; middleware.logger?: boolean (可选) — Log each request through the built-in logger.; middleware.securityHeaders?: boolean (可选) — Attach the built-in security response headers.; middleware.csp?: { policy?: string; nonce?: boolean; reportOnly?: boolean; } (可选) — Content-Security-Policy emission: the policy string, nonce generation, and report-only mode.; middleware.use?: string[] (可选) — Fetch middleware chain (#858), composed around the framework handler in onion order (`use[0]` outermost), outside all built-in middleware above. Each entry is a MODULE PATH (same resolution idiom as `appShell.import`, e.g. './app/middleware/auth.ts') whose default export is a {@link Middleware}; the generated entry emits `import * as __mw_N from '<path>'` and composes `__mw_N.default` in configur…; criticalAssets.fonts?: CriticalFontAsset[] (可选); criticalAssets.styles?: (string | CriticalStyleAsset)[] (可选); criticalAssets.stylesheets?: (string | CriticalStyleAsset)[] (可选) — Alias for styles accepted by config producers.; criticalAssets.inlineScripts?: (string | CriticalInlineScriptAsset)[] (可选); criticalAssets.allowExternalRenderBlocking?: boolean (可选) — Allow intentional external render-blocking styles/scripts.; criticalAssets.allowRenderBlockingExternal?: boolean (可选) — Alias retained only within this build-side config shape.; criticalAssets.minifyInlineStyles?: boolean (可选) — Minify inline CSS. Defaults to true.; criticalAssets.origin?: string (可选) — Origin used to distinguish same-origin and cross-origin absolute URLs.; critical?: CriticalAssetsOptions (可选); i18n?: OpenElementI18nOptions (可选)

Blog options stored in the adapter build context.

contentDir?: string (可选); basePath?: string (可选)

The build's shared mutable state: the resolved framework options, the phase-1/phase-3 metadata, the sub-plugin data slots, and the production plan and artifact records the release and deployment adapters read. One instance is threaded through every adapter plugin for a build.

Minimal build-context contract available to adapter sub-plugins.

plugins: { [key: string]: unknown; blogOptions: OpenElementBlogOptions | null; navSections: OpenElementNavSection[]; headerNav: OpenElementHeaderNavLink[]; sitemapOptio… (必填); registerPlugin: (name: string, instance: unknown) => void (必填)

One header navigation link (href + label) in the generated site nav.

href: string (必填); label: string (必填)

Locale options carried through the build context to the i18n integration.

Project locale declaration. The build expands every static and dynamic route under each additional locale prefix (`/zh/docs`), passes the resolved locale to page `head`/`props` hooks and localizes app-shell navigation. Absent means a single-locale site with no locale prefixing — the pre-i18n output, byte for byte.

locales: string[] (必填) — Locale prefixes the build expands, e.g. `['en', 'zh']`.; defaultLocale?: string (可选) — Locale served without a prefix. Defaults to the first entry.

Navigation section produced by the adapter content pipeline.

section: string (必填); items: { path: string; label: string; order?: number; }[] (必填)

Options for the openElement() unified Vite entry. The framework-options face here is deliberately narrower than the internal {@linkcode FrameworkOptions} transfer type: - the document-head channel is spelled `head` (never `html`), the same spelling `openelement.config.ts` uses — passing `html` fails closed and names the replacement; - the source roots keep their explicit spellings (`routesDir`, `islandsDir`, `componentsDir`), while a config file's `dirs` block is the spelling that also moves the file conventions.

head.title?: string (可选) — Document title; defaults to the package.json `name`.; head.description?: string (可选) — `<meta name="description">` + `og:description`.; head.lang?: string (可选) — `<html lang>`; defaults to `en`.; head.favicon?: string (可选) — Site-root-relative favicon path, emitted as `<link rel="icon">`.; head.ogImage?: string (可选) — `og:image` URL. Absolute (crawlable) or site-root-relative.; head.stylesheets?: string[] (可选) — External stylesheets linked into `<head>`.; head.scripts?: OpenElementHeadScript[] (可选) — External scripts emitted into `<head>`; inline code is not accepted here.; ssg.dynamicRouteFailure?: "fail" | "warn" (可选) — Policy for dynamic-route render failures during SSG. See {@link SsgRenderOptions.dynamicRouteFailure}.; build.outDir?: string (可选) — Output directory for the build artifacts. Defaults to `dist`.; build.manifestBudget?: { islandKB?: number; totalJsKB?: number; pageKB?: number; } (可选) — Advisory only: exceeded budgets print build-manifest warnings and never fail the build; enforce them in your own build-output test.; renderer?: "native" | "lit" (可选) — Page renderer selection (Beta.2.2, #1339). EXPLICIT, never inferred: 'native' (default) renders pages through the compiled Part Program serializer (renderDsd); 'lit' renders LitElement pages through; routesDir?: string (可选) — Directory the route scanner walks, relative to the Vite root. Defaults to `app/routes`.; islandsDir?: string (可选) — Directory island modules are discovered in. Defaults to `app/islands`.; componentsDir?: string (可选) — Directory non-route components live in. Defaults to `app/components`.; packageIslands?: string[] (可选) — Extra package names whose island modules the build admits, e.g. `['@openelement/ui']`.; appShell?: AppShellConfig (可选) — Application shell declaration; `false` disables the shell, `'default'` uses the built-in one.; layouts?: LayoutsConfig (可选) — Per-layout shell declarations keyed by layout name.; mode?: "ssg" (可选) — Build mode. 'ssg' (default) generates static HTML.; headExtras?: string (可选) — @dangerous injected as-is, only use with controlled content; inject.stylesheets?: (string | { href: string; integrity?: string; crossorigin?: "anonymous" | "use-credentials"; attrs?: Record<string, string | number | boolean>; })[] (可选) — Stylesheets linked into the document head; each entry is an href or a link record with integrity/crossorigin/attrs.; inject.scripts?: (string | { src: string; type?: string; async?: boolean; defer?: boolean; integrity?: string; crossorigin?: "anonymous" | "use-credentials"; attrs?: Record<str… (可选) — Scripts emitted into the document; each entry is a src or a script record with type/async/defer/integrity/crossorigin/attrs.; inject.headFragments?: string[] (可选) — @dangerous fragments injected as-is. Trust boundary (same level as `trustedHtml`): never concatenate user-controlled content into these fragments; sanitize untrusted data at your own system boundary first. The framework only enforces no-`<script>` and no-executable-`<style>`.; ssr.noExternal?: (string | RegExp)[] (可选); island.upgradeStrategy?: "load" | "idle" | "visible" | "only" (可选); viewTransition?: boolean (可选) — Enable the View Transitions API for client navigations. Defaults to true.; speculation?: boolean | { prerender?: string[]; prefetch?: string[]; exclude?: string[]; eagerness?: "immediate" | "moderate" | "conservative"; } (可选) — Speculation Rules emission: `true` uses framework defaults, or pass prerender/prefetch URL lists, exclusions and an eagerness.; middleware.cors?: boolean (可选) — Enable the built-in CORS middleware.; middleware.corsOrigin?: string | string[] (可选) — Static CORS allowlist data, serialized into the generated entry as JSON. Mutually exclusive with {@link FrameworkOptions.middleware.corsOriginModule }.; middleware.corsOriginModule?: string (可选) — Path to a module that default-exports `(origin: string) => string | undefined`. The generated entry imports the module — the callback is never serialized — so it may close over module scope and import dependencies. Resolved with the same idiom as `appShell.import` (e.g. './app/cors-origin.ts'). Mutually exclusive with `corsOrigin`.; middleware.requestId?: boolean (可选) — Emit and honor a per-request id header.; middleware.logger?: boolean (可选) — Log each request through the built-in logger.; middleware.securityHeaders?: boolean (可选) — Attach the built-in security response headers.; middleware.csp?: { policy?: string; nonce?: boolean; reportOnly?: boolean; } (可选) — Content-Security-Policy emission: the policy string, nonce generation, and report-only mode.; middleware.use?: string[] (可选) — Fetch middleware chain (#858), composed around the framework handler in onion order (`use[0]` outermost), outside all built-in middleware above. Each entry is a MODULE PATH (same resolution idiom as `appShell.import`, e.g. './app/middleware/auth.ts') whose default export is a {@link Middleware}; the generated entry emits `import * as __mw_N from '<path>'` and composes `__mw_N.default` in configur…; criticalAssets.fonts?: CriticalFontAsset[] (可选); criticalAssets.styles?: (string | CriticalStyleAsset)[] (可选); criticalAssets.stylesheets?: (string | CriticalStyleAsset)[] (可选) — Alias for styles accepted by config producers.; criticalAssets.inlineScripts?: (string | CriticalInlineScriptAsset)[] (可选); criticalAssets.allowExternalRenderBlocking?: boolean (可选) — Allow intentional external render-blocking styles/scripts.; criticalAssets.allowRenderBlockingExternal?: boolean (可选) — Alias retained only within this build-side config shape.; criticalAssets.minifyInlineStyles?: boolean (可选) — Minify inline CSS. Defaults to true.; criticalAssets.origin?: string (可选) — Origin used to distinguish same-origin and cross-origin absolute URLs.; critical?: CriticalAssetsOptions (可选); i18n?: OpenElementI18nOptions (可选)

Options for the `.mdx` route plugin ({@linkcode mdxPlugin}).

routesDir?: string (可选) — Routes directory (as configured in openElement()). The compiled page tag derives from the route-file-relative path so the generated entry's path-derived registration tag matches the program tag.

Low-level Vite plugin pipeline: SSR dev server, SSG and islands without the content/i18n conveniences of `openElement()`.

mode?: "ssg" (可选) — Build/dev mode. 'ssg' (default) enables SSR dev server + static generation.; routes.dir?: string (可选); output.outDir?: string (可选); island.dir?: string (可选); island.upgradeStrategy?: string (可选); viewTransition?: boolean (可选); headExtras?: string (可选)

Options for the low-level {@linkcode openPipeline} Vite plugin pipeline.

mode?: "ssg" (可选) — Build/dev mode. 'ssg' (default) enables SSR dev server + static generation.; routes.dir?: string (可选); output.outDir?: string (可选); island.dir?: string (可选); island.upgradeStrategy?: string (可选); viewTransition?: boolean (可选); headExtras?: string (可选)

Speculation Rules configuration for SSG post-processing

prerender?: string[] (可选) — URL patterns to prerender (fully render in background before navigation).; prefetch?: string[] (可选) — URL patterns to prefetch (fetch HTML + resources without rendering).; exclude?: string[] (可选) — URL patterns to exclude from both prefetch and prerender.; eagerness?: "immediate" | "moderate" | "conservative" (可选) — Eagerness level for prerender rules.

User-facing SSG build behavior switches (OpenElementOptions['ssg']).

dynamicRouteFailure?: "fail" | "warn" (可选) — Policy for dynamic-route render failures during SSG. See {@link SsgRenderOptions.dynamicRouteFailure}.

Deno permissions the bootstrap needs. Owner ruling 2026-09-21: the documented command uses bare `-A` — the consumer scaffolds their own project, and the scoped-permission form reads as noise (the same ruling narrowed the `check-no-allow-all` tripwire to an exact-line exemption for this command). `--minimum-dependency-age 0` is a functional footnote kept in prose where needed, not part of the documented shape.

The dist-tag the documented install resolves; the exact version is registry truth.

The npm specifier the generator is published under.

Placeholder the usage text and the docs use in place of a project name.

Build the canonical install command for `projectName`. `projectName` defaults to the placeholder so callers that document the command shape (usage output) and callers that show a concrete example share one builder and therefore one flag list.

The build-time generated package manifest (declarations for every UI component).

Compact status badge backed by Open Props semantic tokens.

Minimal button component following Swiss International Style.

Callout/notice box for inline documentation alerts.

Minimal card container with optional header and footer.

Token-color rationale (the styles below ship to clients, so this note stays out of the template): the vendored light-DOM Prism theme's comment gray #708090 is 3.6:1 on its own #f5f2f0 background (under AA), but that pairing never renders — the vendor only paints it through pre[class*=language-] and site fences carry the language class on code, not pre. A host site that pins its code surface to --bg-code/#0d0f12 (pre[class*=language-] override) measures 4.7:1 there.

Dialog component using native <dialog> element + popover API.

Popover-API dropdown with CSS Anchor Positioning placement.

Minimal input field following Swiss International Style.

The full token set as one constructable sheet. The token block selects `:root, :host`, so the same sheet serves a document-level adoption and a shadow-root adoption; only the structural fallback is :host-exclusive.

WAI-ARIA tabs pattern. The slotted [slot="tab"] and [slot="panel"] elements

Theme toggle Reactive DSD component for Dark/Light mode switching.

Explicitly register every first-party UI element. Safe to call repeatedly.

define: (name: string, constructor: CustomElementConstructor, options?: ElementDefinitionOptions) => void (必填) — The **`define()`** method of the CustomElementRegistry interface adds a definition for a custom element to the custom element registry, mapping its name to the constructor which will be used to create it. [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomElementRegistry/define); get: (name: string) => CustomElementConstructor (必填) — The **`get()`** method of the CustomElementRegistry interface returns the constructor for a previously-defined custom element. [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomElementRegistry/get); getName: (constructor: CustomElementConstructor) => string | null (必填) — The **`getName()`** method of the CustomElementRegistry interface returns the name for a previously-defined custom element. [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomElementRegistry/getName); initialize: (root: Node) => void (必填); upgrade: (root: Node) => void (必填) — The **`upgrade()`** method of the CustomElementRegistry interface upgrades all shadow-containing custom elements in a Node subtree, even before they are connected to the main document. [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomElementRegistry/upgrade); whenDefined: (name: string) => Promise<CustomElementConstructor> (必填) — The **`whenDefined()`** method of the CustomElementRegistry interface returns a Promise that resolves when the named element is defined. [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomElementRegistry/whenDefined)

Compact status badge backed by Open Props semantic tokens.

Minimal button component following Swiss International Style.

Callout/notice box for inline documentation alerts.

Minimal card container with optional header and footer.

Token-color rationale (the styles below ship to clients, so this note stays out of the template): the vendored light-DOM Prism theme's comment gray #708090 is 3.6:1 on its own #f5f2f0 background (under AA), but that pairing never renders — the vendor only paints it through pre[class*=language-] and site fences carry the language class on code, not pre. A host site that pins its code surface to --bg-code/#0d0f12 (pre[class*=language-] override) measures 4.7:1 there.

Dialog component using native <dialog> element + popover API.

Popover-API dropdown with CSS Anchor Positioning placement.

Minimal input field following Swiss International Style.

The full token set as one constructable sheet. The token block selects `:root, :host`, so the same sheet serves a document-level adoption and a shadow-root adoption; only the structural fallback is :host-exclusive.

The full token set as one constructable sheet. The token block selects `:root, :host`, so the same sheet serves a document-level adoption and a shadow-root adoption; only the structural fallback is :host-exclusive.

WAI-ARIA tabs pattern. The slotted [slot="tab"] and [slot="panel"] elements

Theme toggle Reactive DSD component for Dark/Light mode switching.