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. 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 #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@386: (hint: string) => symbol (必填) — Converts a Symbol object to a symbol.; key.__@toStringTag@388: 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@386: (hint: string) => symbol (必填) — Converts a Symbol object to a symbol.; key.__@toStringTag@388: 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@386: (hint: string) => symbol (必填) — Converts a Symbol object to a symbol.; __@toStringTag@388: 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 #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'.

Idle-hydration scheduling fallback (milliseconds) when neither `requestIdleCallback` nor `requestAnimationFrame` is available.

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 (必填)

Request-body bound (bytes) the generated entry applies to action POST routes; larger uploads belong on API routes with explicit limits.

Nested element expansion depth bound for `renderDsd`: cyclic component composition fails closed instead of recursing without end.

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 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.status?: "stable" | "experimental" (可选) — Stability marker from the owning package's manifest policy.; 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 (#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 (必填); __@[email protected]: () => 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 (#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 (#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.

Deferred fields (declared streamed properties) one stream route's manifest may carry. The build scan, the server executor, and the browser seed contract enforce the same bound.

Part/Region owners one stream route's manifest may address in total across all deferred fields.

Serialized stream payload bound, as a string length in UTF-16 code units: one seed attribute or one deferred frame's markup may not exceed it. The server checks the JSON text and the rendered range before emitting; the browser checks the attribute before parsing.

Typed properties one streamed seed may carry: the browser seed contract rejects the WHOLE seed above this count, so an oversized component would silently fail to hydrate instead of failing loud at the server.

Deferred-field resolution budget (milliseconds) for one streamed response: fields still pending when it expires are failed in place and the stream ends with the shell and whatever resolved.

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.

Request-body bound (bytes) the generated entry applies to action POST routes; larger uploads belong on API routes with explicit limits.

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

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

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.

Deferred fields (declared streamed properties) one stream route's manifest may carry. The build scan, the server executor, and the browser seed contract enforce the same bound.

Part/Region owners one stream route's manifest may address in total across all deferred fields.

Serialized stream payload bound, as a string length in UTF-16 code units: one seed attribute or one deferred frame's markup may not exceed it. The server checks the JSON text and the rendered range before emitting; the browser checks the attribute before parsing.

Typed properties one streamed seed may carry: the browser seed contract rejects the WHOLE seed above this count, so an oversized component would silently fail to hydrate instead of failing loud at the server.

Deferred-field resolution budget (milliseconds) for one streamed response: fields still pending when it expires are failed in place and the stream ends with the shell and whatever resolved.

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. 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 #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@1741: (hint: string) => symbol (必填) — Converts a Symbol object to a symbol.; key.__@toStringTag@1743: 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@1741: (hint: string) => symbol (必填) — Converts a Symbol object to a symbol.; key.__@toStringTag@1743: 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@1741: (hint: string) => symbol (必填) — Converts a Symbol object to a symbol.; __@toStringTag@1743: 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 #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'.

Idle-hydration scheduling fallback (milliseconds) when neither `requestIdleCallback` nor `requestAnimationFrame` is available.

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 (必填)

Request-body bound (bytes) the generated entry applies to action POST routes; larger uploads belong on API routes with explicit limits.

Nested element expansion depth bound for `renderDsd`: cyclic component composition fails closed instead of recursing without end.

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 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.status?: "stable" | "experimental" (可选) — Stability marker from the owning package's manifest policy.; 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 (#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 (必填); __@[email protected]: () => 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 (#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 (#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.

Deferred fields (declared streamed properties) one stream route's manifest may carry. The build scan, the server executor, and the browser seed contract enforce the same bound.

Part/Region owners one stream route's manifest may address in total across all deferred fields.

Serialized stream payload bound, as a string length in UTF-16 code units: one seed attribute or one deferred frame's markup may not exceed it. The server checks the JSON text and the rendered range before emitting; the browser checks the attribute before parsing.

Typed properties one streamed seed may carry: the browser seed contract rejects the WHOLE seed above this count, so an oversized component would silently fail to hydrate instead of failing loud at the server.

Deferred-field resolution budget (milliseconds) for one streamed response: fields still pending when it expires are failed in place and the stream ends with the shell and whatever resolved.

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 scan's factory vocabulary is host-injected: the default knows only the element package's own registration factories, and page-definition/registration facts for other packages require the caller's {@link ModuleSemanticsOptions.vocabulary} descriptors.

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.; staticSidecars?: readonly StaticSidecarDescriptor[] (可选) — Static-sidecar descriptors the host application admits into the compiled module grammar (e.g. its island delivery policy factory). The default core knows none: without an injected descriptor a module carrying a sidecar policy statement fails closed with OEC9008.

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. `options.staticSidecars` admits host-declared sidecar policy statements (e.g. an island delivery descriptor); the default core admits none.

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 (必填) — True when the module default-exports a page-definition factory call from the host's injected vocabulary, or is an .mdx route. The default scan (no injected vocabulary) never recognizes another package's factories.; usesExportedTagName: boolean (必填); enhancedForm: boolean (必填); defaultCompiledTag?: string (可选); definedCustomElementTags: string[] (必填); referencedCustomElementTags: string[] (必填); compilerInteractionEvents: string[] (必填)

Host-supplied vocabulary extensions for the module scan.

vocabulary?: readonly ModuleVocabularyDescriptor[] (可选) — Vocabulary descriptors the host admits beyond the core's own element bindings. The default scan knows no other package: a route module's page-definition export or registration factory is recognized only when the host injects its descriptor.

One module-scan vocabulary entry the host admits: a binding identity (module specifier + exported name, aliases followed) plus the fact a canonical call of that binding contributes. Plain data — the scan consumes the descriptors without learning the caller's package vocabulary, the same direction as the compiler's {@link StaticSidecarDescriptor} admission (#1473 item 3).

moduleSpecifier: string (必填) — Canonical module specifier the factory must be imported from.; exportName: string (必填) — Exported name of the factory binding.; kind: "page-definition" | "element-registration" (必填) — What a canonical call of the binding contributes to the scan.

Host-supplied admission extensions for the semantic core.

staticSidecars?: readonly StaticSidecarDescriptor[] (可选) — Static-sidecar descriptors the host admits. The default core knows none: a module carrying a sidecar policy statement fails closed until the host injects its descriptor.

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.

A compile-time binding a host application teaches the semantic core beyond the built-in element intrinsics. Admission stays a binding identity: the export must arrive as a runtime named import from the canonical specifier (aliases followed); namespace, default, type-only, conflicting and relative-re-export provenance is never admitted.

moduleSpecifier: string (必填) — Canonical module specifier the sidecar export must be imported from.; exportName: string (必填) — Exported name of the sidecar factory binding.; kind: "static-sidecar" (必填) — The admission granted: a colocated static policy statement.

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 #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 (#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.; staticSidecars?: readonly StaticSidecarDescriptor[] (可选) — Static-sidecar descriptors the host application admits into the compiled module grammar (e.g. its island delivery policy factory). The default core knows none: without an injected descriptor a module carrying a sidecar policy statement fails closed with OEC9008.

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. 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 #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 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 (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 (decision 0143; canonical/alternates in #1326; structured data via the typed JSON-LD channel). 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 (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 (#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 framework client script a resolved document embeds before `</body>`. Shape-compatible with the serializer's script descriptors, so the document channel routes it through without conversion; entries without src or code are meaningless and rejected at resolution (never silently dropped).

src?: string (可选) — External script URL (attribute-escaped at serialization).; code?: string (可选) — Inline script body. Trusted framework input, never user content.; type?: string (可选) — Script type attribute, e.g. 'module'; omitted means a classic script.

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[] (可选); clientScripts?: ClientScriptDescriptor[] (可选) — The framework client scripts this document embeds before `</body>` — structured descriptors rendered by the serializer at document time (#1471), never by post-build HTML surgery. The serializer attaches the per-request CSP nonce; SSG output carries none.; 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. `clientScripts` carries the framework's client-script descriptors (the build's client asset manifest — the render wiring hands them in, they are never author head data); they are validated like every other field and become part of the resolved document, so every render channel — the SSG render pass included — serializes the final script tags from one place.

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').

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.

The fetch-channel 500 (#863, #558): an unexpected action rejection answers RFC 9457 problem+json with internals scrubbed in production (the detail degrades to the reason phrase; development keeps the message for debugging). The native channel stays on the generated handler's HTML error boundary. `production` is the entry's `import.meta.env.PROD`, injected so this module stays free of build-tool globals.

req: { readonly url: string; readonly raw: Request; header(name: string): string | undefined; } (必填); header: (name: string, value: string) => void (必填); get: (key: string) => unknown (必填); json: (object: unknown, status?: number, headers?: Record<string, string>) => Response (必填); text: (text: string, status?: number, headers?: Record<string, string>) => Response (必填); redirect: (location: string, status?: number) => Response (必填); res: Response (必填) — The response under construction (read by the middleware bridge fallback).

What one protocol run hands back to the generated handler.

response?: Response (可选) — When set, the handler returns this response and renders nothing.; actionResult?: ActionOutcome (可选) — The classified action outcome for the 422 re-render (native failure path).

The slice of the Hono request context the action protocol touches. The generated entry passes its real Hono context; the narrow shape keeps this module unit-testable without hono.

req: { readonly url: string; readonly raw: Request; header(name: string): string | undefined; } (必填); header: (name: string, value: string) => void (必填); get: (key: string) => unknown (必填); json: (object: unknown, status?: number, headers?: Record<string, string>) => Response (必填); text: (text: string, status?: number, headers?: Record<string, string>) => Response (必填); redirect: (location: string, status?: number) => Response (必填); res: Response (必填) — The response under construction (read by the middleware bridge fallback).

The load context the generated handler built; actions receive it plus `formData`.

The per-request action channel state: mutated by {@linkcode runActionProtocol} before any protocol exit so the generated handler's catch block can branch on the fetch path.

isFetch: boolean (必填)

The redirect exit for a POST action: every 3xx an author throws out of an action is coerced to 303 — PRG must be method-safe and non-cacheable. The native form channel answers a real 303; the fetch channel answers HTTP 200 with the redirect carried as the ActionResult body (`{ type: 'redirect', status: 303, location }`) — the serialized client executor matches on the body, not the HTTP status. GET handlers keep the author's status (the generated catch emits that branch itself).

req: { readonly url: string; readonly raw: Request; header(name: string): string | undefined; } (必填); header: (name: string, value: string) => void (必填); get: (key: string) => unknown (必填); json: (object: unknown, status?: number, headers?: Record<string, string>) => Response (必填); text: (text: string, status?: number, headers?: Record<string, string>) => Response (必填); redirect: (location: string, status?: number) => Response (必填); res: Response (必填) — The response under construction (read by the middleware bridge fallback).

Instantiates a generated CSP policy template for one request: replaces the first `NONCE_PLACEHOLDER` marker with the request nonce. The template is build-time data (route wiring produced it from the author's `middleware.csp` policy); only this substitution is runtime semantics.

The app-shell runtime bound into the generated entry.

resolveAppShell: (routeMeta?: Record<string, unknown>) => ResolvedAppShell (必填) — Resolve the shell for one route's metadata: `layout: false` disables the shell, a named layout looks up `appShellPlan.layouts`, anything else (and an unset layout) takes the plan default.; renderAppShell: (pageHtml: unknown, routePath: string, options?: { locale?: string; routeMeta?: Record<string, unknown>; }) => string (必填) — Render route content inside the resolved app shell layout: the page HTML is projected into the shell's default slot through the page renderer, so nested admitted islands expand deterministically and route content stays inside the declared layout-main boundary. An unresolved shell returns the content unchanged.

What {@linkcode createAppShellRuntime} binds: the entry's Element imports plus its serialized plan data.

ssr: PageSsrRenderer (必填) — The entry's bound page renderer (`__ssr`) — the shell renders through the same seam.; trustedHtml: (html: string) => TrustedHtmlValue (必填) — The entry's `trustedHtml` import — the slot projection is an explicit trust boundary.; appShellPlan: AppShellPlan (必填) — The build's shell plan (serialized generated data).; locales: readonly string[] (必填) — Declared project locales (serialized generated data).; navSections: readonly unknown[] (必填) — Nav sections (serialized generated data; empty on the 1.0 surface).; headerNav: readonly Record<string, unknown>[] (必填) — Header nav links (serialized generated data; empty on the 1.0 surface).; defaultLocale: string (必填) — The project's default locale (generated data).

Startup guard for a page route under the compiled stream runtime: the route's literal stream declaration must match the build-time manifest (field list, program tag, program version) and the module must carry the compiled Part Program the manifest was derived from. Moved verbatim from the emitted `__assertStreamRoute` body.

Startup guard for a page route under a renderer without compiled-stream support (the lit fork): a route declaring `renderIntent.stream` fails the build loudly instead of silently rendering static. Moved verbatim from the emitted `__assertLitStreamRoute` body.

The default body-limit middleware for action POST routes (#568), bound to the serialized `MAX_ACTION_BODY_BYTES` policy constant (see the module doc): an oversized body answers the fetch channel with problem+json 413 (same fork as the CSRF 403) and the native form channel with plain text. The no-store/Vary negotiation headers ride every 413 like every other action response. Larger uploads belong on API routes with explicit limits.

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.

Binds the app-shell runtime to the entry's renderer, trust boundary, and serialized shell/nav/locale data. The entry destructures `{ resolveAppShell: __resolveAppShell, renderAppShell: __renderAppShell }`.

ssr: PageSsrRenderer (必填) — The entry's bound page renderer (`__ssr`) — the shell renders through the same seam.; trustedHtml: (html: string) => TrustedHtmlValue (必填) — The entry's `trustedHtml` import — the slot projection is an explicit trust boundary.; appShellPlan: AppShellPlan (必填) — The build's shell plan (serialized generated data).; locales: readonly string[] (必填) — Declared project locales (serialized generated data).; navSections: readonly unknown[] (必填) — Nav sections (serialized generated data; empty on the 1.0 surface).; headerNav: readonly Record<string, unknown>[] (必填) — Header nav links (serialized generated data; empty on the 1.0 surface).; defaultLocale: string (必填) — The project's default locale (generated data).

Creates one per-request CSP nonce: a UUID without its dashes (32 hex characters). The CSP middleware embeds this value into the `script-src 'nonce-…'` policy it sets on the response and exposes it to the handlers as the `cspNonce` Hono context variable.

The per-route shell gate the streamed handlers await before any streamed document exists: the route must resolve its build manifest, the page class must carry the compiled Part Program, and both must agree on tag and program version — the gate fails closed with the route before the executor re-verifies the wire hash (#1276 B1.3-F1). Bound to the entry's serialized manifests and its `createDeferredDsdExecutor` import; the returned gate is the `__createDeferredPageShell` call site (Amendment 1 — the last runtime function body that stayed emitted for its oracle pin).

streamManifests: Record<string, StreamRouteManifest> (必填) — The entry's serialized route→stream-manifest build data (`__streamManifests`).; createDeferredDsdExecutor: (options: { componentClass: unknown; props?: unknown; manifest: StreamRouteManifest; instanceId: string; documentToken?: string; }) => Promise<StreamExecutorVi… (必填) — The entry's `createDeferredDsdExecutor` import — the deferred shell it produces is the pump's executor view.

Assembles the generated Hono app from the entry's route descriptor. Pure factory: descriptor data in, handler contract out — every emitted call site in the entry binds a property of the returned record.

islands: Record<string, string> (必填) — Build-time island map: tag -> client module path (#951 upgrade URLs).; appShellPlan: AppShellPlan (必填) — The build's shell plan (serialized generated data).; locales: readonly string[] (必填) — Declared project locales (serialized generated data).; navSections: readonly unknown[] (必填) — Nav sections (serialized generated data; empty on the 1.0 surface).; headerNav: readonly Record<string, unknown>[] (必填) — Header nav links (serialized generated data; empty on the 1.0 surface).; defaultLocale: string (必填) — The project's default locale (generated data).; devClientScriptSrc: string | null (必填) — The dev island-client URL the entry computed from its compile-time `import.meta.env` constants; null when the app ships no client entry.; pageHandlerPaths: readonly string[] (必填) — Page route paths, in route order — the handler table's keys.; fetchMiddleware?: readonly FetchMiddleware[] (可选) — `middleware.use` module defaults, user-configured order (use[0] outermost).; pageRuntime?: GeneratedPageRuntime (可选)

Creates the per-entry Hono bridge the generated handlers compose through.

The lit renderer (#1339): render a registered LitElement page host to DSD HTML through

renderLitPageToHtml: (input: { tag: string; props?: Record<string, unknown>; }) => { html: string; } (必填) — `renderLitPageToHtml` — the registered LitElement page host renders to DSD HTML.

The 405 responder handed to `createRouteMiddleware` as `methodNotAllowed`: no-store (request-time responses are never cacheable), the action negotiation `Vary`, and the `Allow` header listing the route's methods (#572). Reads the bridged per-request Hono context so the WinterCG-side middleware can still answer with the Hono text channel.

delete: (key: object) => boolean (必填) — Removes the specified element from the WeakMap.; get: (key: object) => ActionHonoContext (必填) — @returns a specified element.; has: (key: object) => boolean (必填) — @returns a boolean indicating whether an element with the specified key exists or not.; set: (key: object, value: ActionHonoContext) => WeakMap<object, ActionHonoContext> (必填) — Adds a new element with a specified key and value.; getOrInsert: (key: object, defaultValue: ActionHonoContext) => ActionHonoContext (必填) — Returns a specified element from the WeakMap object. If no element is associated with the specified key, a new element with the value `defaultValue` will be inserted into the WeakMap and returned.; getOrInsertComputed: (key: object, callback: (key: object) => ActionHonoContext) => ActionHonoContext (必填) — Returns a specified element from the WeakMap object. If no element is associated with the specified key, the result of passing the specified key to the `callback` function will be inserted into the WeakMap and returned.; __@toStringTag@4901: string (必填)

The native renderer (default): render a registered compiled element class through Element composition. Fails closed for invalid tags, depth-bound violations, and unregistered hosts — an unknown OpenElement host cannot be server-rendered (client-only and foreign tags pass through per the admission plan).

renderDsd: (tag: string, options: { componentClass?: unknown; props?: Record<string, unknown>; sourceInfo?: PageSsrSourceInfo; ssrRenderableTags?: readonly string[]; proj… (必填) — Element's sync compiled serializer (`renderDsd`).; customElements: { get(tag: string): unknown; } (必填) — The SSR registry (the runtime's `customElements` global).; ssrRenderableTags: readonly string[] (必填) — Build-admitted nested compiled tags (serialized generated data).

Creates the per-path page handler table the generated GET/POST wiring populates: one mutable method record per page path, keyed by the route path literal the wiring emits. (Previously emitted inline as `Object.fromEntries([...].map(path => [path, {}]))`.)

Binds the page props projection to the generated entry's serialized dangerous-key list. Returns the three projection seams under their generated binding names (`__pageProps`, `__pageErrorProps` — the entry destructures them).

dangerousKeys: ReadonlySet<string> (必填) — The canonical dangerous-key set (the factory imports it from the kernel-free /authoring leaf): one rule, no second copy.

Binds the status-page renderer to the entry's `escapeHtml` import. Both the native and the lit entry import the same canonical escaper (@openelement/element[/html]), so the one implementation serves every status channel (404 fallbacks, render failures, SSG redirect pages).

Binds the streaming body builder to the entry's injected Element function (and the policy timeout default): the returned builder is the `__streamBody` call site the generated handler invokes once per streamed response.

escapeAttr: (value: string) => string (必填) — The entry's `escapeAttr` import — an Element function, injected so this module stays free of an Element runtime edge.; timeoutMs.toString: (radix?: number) => string (必填) — Returns a string representation of an object.; timeoutMs.toFixed: (fractionDigits?: number) => string (必填) — Returns a string representing a number in fixed-point notation.; timeoutMs.toExponential: (fractionDigits?: number) => string (必填) — Returns a string containing a number represented in exponential notation.; timeoutMs.toPrecision: (precision?: number) => string (必填) — Returns a string containing a number represented either in exponential or fixed-point notation with a specified number of digits.; timeoutMs.valueOf: () => number (必填) — Returns the primitive value of the specified object.; timeoutMs.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.

Creates the per-request response-header channel for a streamed route: the author-facing `Headers` proxy plus its commitment switch. The proxy guards the mutating members (`append`, `set`, `delete`) after {@linkcode ResponseHeaderChannel.commit}: a late write from a held `context.responseHeaders` reference is a no-op with a structured diagnostic naming the route, header, and operation (the no-op rule; it never throws and never reinterprets a late `Location`/`Set-Cookie` as a protocol decision). Every other member — reads, `forEach` included — behaves exactly like the wrapped `Headers`, and `forEach` hands the callback the proxy itself so a callback-held reference is gated the same way. `route` only feeds the diagnostic payload.

The request scope for one streamed route: the loader's `request.signal` aborts when the client disconnects (upstream abort fan-out), the response body's `cancel()` tears the whole scope down, and {@linkcode * StreamRequestScope.abortWork} aborts pending loader work at the timeout without cancelling the still-open response.

cache: RequestCache (必填) — The **`cache`** read-only property of the Request interface contains the cache mode of the request. It controls how the request will interact with the browser's HTTP cache. [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/cache); credentials: RequestCredentials (必填) — The **`credentials`** read-only property of the Request interface reflects the value given to the Request() constructor in the credentials option. It determines whether or not the browser sends credentials with the request, as well as whether any Set-Cookie response headers are respected. [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/credentials); destination: RequestDestination (必填) — The **`destination`** read-only property of the Request interface returns a string describing the type of content being requested. [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/destination); headers: Headers (必填) — The **`headers`** read-only property of the Request interface contains the Headers object associated with the request. [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/headers); integrity: string (必填) — The **`integrity`** read-only property of the Request interface contains the subresource integrity value of the request. [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/integrity); keepalive: boolean (必填) — The **`keepalive`** read-only property of the Request interface contains the request's keepalive setting (true or false), which indicates whether the browser will keep the associated request alive if the page that initiated it is unloaded before the request is complete. [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/keepalive); method: string (必填) — The **`method`** read-only property of the Request interface contains the request's method (GET, POST, etc.) [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/method); mode: RequestMode (必填) — The **`mode`** read-only property of the Request interface contains the mode of the request (e.g., cors, no-cors, same-origin, or navigate.) This is used to determine if cross-origin requests lead to valid responses, and which properties of the response are readable. [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/mode); redirect: RequestRedirect (必填) — The **`redirect`** read-only property of the Request interface contains the mode for how redirects are handled. [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/redirect); referrer: string (必填) — The **`referrer`** read-only property of the Request interface is set by the user agent to be the referrer of the Request. (e.g., client, no-referrer, or a URL.) [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/referrer); referrerPolicy: ReferrerPolicy (必填) — The **`referrerPolicy`** read-only property of the Request interface returns the referrer policy, which governs what referrer information, sent in the Referer header, should be included with the request. [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/referrerPolicy); signal: AbortSignal (必填) — The read-only **`signal`** property of the Request interface returns the AbortSignal associated with the request. [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/signal); url: string (必填) — The **`url`** read-only property of the Request interface contains the URL of the request. [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/url); clone: () => Request (必填) — The **`clone()`** method of the Request interface creates a copy of the current Request object. [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/clone); body: ReadableStream<Uint8Array<ArrayBuffer>> | null (必填) — [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/body); bodyUsed: boolean (必填) — [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/bodyUsed); arrayBuffer: () => Promise<ArrayBuffer> (必填) — [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/arrayBuffer); blob: () => Promise<Blob> (必填) — [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/blob); bytes: () => Promise<Uint8Array<ArrayBuffer>> (必填) — [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/bytes); formData: () => Promise<FormData> (必填) — [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/formData); json: () => Promise<any> (必填) — [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/json); text: () => Promise<string> (必填) — [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/text)

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

The entry bindings the deferred-shell gate reads. `streamManifests` is the generated `__streamManifests` build data; the executor creator is the entry's `createDeferredDsdExecutor` Element import, injected so this module stays free of an Element runtime edge (#1339).

streamManifests: Record<string, StreamRouteManifest> (必填) — The entry's serialized route→stream-manifest build data (`__streamManifests`).; createDeferredDsdExecutor: (options: { componentClass: unknown; props?: unknown; manifest: StreamRouteManifest; instanceId: string; documentToken?: string; }) => Promise<StreamExecutorVi… (必填) — The entry's `createDeferredDsdExecutor` import — the deferred shell it produces is the pump's executor view.

Everything the generated entry destructures and re-exports.

app: Hono<BlankEnv, BlankSchema, "/"> (必填) — The Hono app — the entry's default export.; hono: HonoBridge (必填) — The internal Hono↔WinterCG bridge: `contexts` feeds the entry's `app.all('*')` request hook, `asFetchHandler`/`asFetchMiddleware` adapt every generated page handler onto the WinterCG route middleware.; handler: (request: Request, context?: { env?: unknown; platform?: unknown; }) => Promise<Response> (必填) — The WinterCG request handler: `app.fetch` with the fetch-middleware onion composed around it when `middleware.use` is configured (#858).; devFetch?: { fetch: (request: Request, env: unknown, executionContext: unknown) => Promise<Response>; } (可选) — Dev-server boundary export, present only with `middleware.use` (#858).; runtimeAdapter: Record<string, unknown> (必填) — Deployment adapter record (`openElementRuntimeAdapter`).; pageHandlers: Record<string, Record<string, unknown>> (必填) — Per-path page handler table the generated GET/POST wiring populates.; apiRouteRecords: { id: string; path: string; handlers: unknown; }[] (必填) — API route records the generated API wiring pushes into.; methodNotAllowed: (request: Request, allow: string[]) => Response (必填) — The 405 responder for `createRouteMiddleware({ methodNotAllowed })` (#572).; actionBodyLimit: MiddlewareHandler (必填) — The default action body-limit middleware (#568), bound to the policy constant.; registerSsrComponent: (tag: string, ctor: unknown) => void (必填) — SSR registration seam (security.ts).; setRequestTimeClientScript: (src: string | null | undefined) => void (必填) — Request-time client-script src setter (`dist/server/index.js` startup).; clientScriptDescriptors: () => Array<{ type: "module"; src: string; }> (必填) — wrapInDocument `scripts` descriptors for the current runtime mode (#951).; locales: readonly string[] (必填); getDefaultLocale: () => string (必填); ssr?: PageSsrRenderer (可选) — Page-render bindings — present only when the config carried `pageRuntime`.; pageProps?: ((routeModule: unknown, context: PageContext) => ProjectedProps) (可选); pageErrorProps?: ((routeModule: unknown, error: unknown, context: PageContext) => ProjectedProps) (可选); statusHtml?: StatusHtmlRenderer (可选); resolveAppShell?: ((routeMeta?: Record<string, unknown>) => ResolvedAppShell) (可选); renderAppShell?: ((pageHtml: unknown, routePath: string, options?: { locale?: string; routeMeta?: Record<string, unknown>; }) => string) (可选)

The route-descriptor data the generated entry hands the factory.

islands: Record<string, string> (必填) — Build-time island map: tag -> client module path (#951 upgrade URLs).; appShellPlan: AppShellPlan (必填) — The build's shell plan (serialized generated data).; locales: readonly string[] (必填) — Declared project locales (serialized generated data).; navSections: readonly unknown[] (必填) — Nav sections (serialized generated data; empty on the 1.0 surface).; headerNav: readonly Record<string, unknown>[] (必填) — Header nav links (serialized generated data; empty on the 1.0 surface).; defaultLocale: string (必填) — The project's default locale (generated data).; devClientScriptSrc: string | null (必填) — The dev island-client URL the entry computed from its compile-time `import.meta.env` constants; null when the app ships no client entry.; pageHandlerPaths: readonly string[] (必填) — Page route paths, in route order — the handler table's keys.; fetchMiddleware?: readonly FetchMiddleware[] (可选) — `middleware.use` module defaults, user-configured order (use[0] outermost).; pageRuntime?: GeneratedPageRuntime (可选)

The page-render seam the entry's Element imports feed (renderer-adapter selected). Present only when the entry has page routes: an API-only entry imports no Element renderer and binds none of it.

mode: "native" | "lit" (必填); ssrRenderableTags: readonly string[] (必填) — Build-admitted SSR-renderable tags (serialized generated data).; trustedHtml: (html: string) => TrustedHtmlValue (必填); escapeHtml: (value: string) => string (必填); renderDsd?: ((tag: string, options: { componentClass?: unknown; props?: Record<string, unknown>; sourceInfo?: PageSsrSourceInfo; ssrRenderableTags?: readonly string[]; pro… (可选) — native only: the compiled serializer and the SSR registry.; customElements?: { get(tag: string): unknown; } (可选); renderLitPageToHtml?: ((input: { tag: string; props?: Record<string, unknown>; }) => { html: string; }) (可选) — lit only: the lit-ssr page renderer.

The internal Hono↔WinterCG bridge (never user-visible): the WinterCG route middleware from

contexts: WeakMap<object, ActionHonoContext> (必填) — Request → Hono context, populated by the entry's `app.all('*')` hook.; asFetchHandler: (handler: (context: ActionHonoContext, route: unknown) => unknown) => (request: Request, route: unknown, next: () => unknown) => unknown (必填) — Adapts a Hono-dialect handler onto the WinterCG `(request, route)` shape.; asFetchMiddleware: (middleware: (context: ActionHonoContext, next: () => unknown) => unknown) => (request: Request, route: unknown, next: () => unknown) => Promise<unknown> (必填) — Adapts a Hono-dialect middleware onto the WinterCG onion shape.

Installs the SSR registry guard and returns its registration seam. Behavior contract (moved verbatim from the generated entry): - The TRUE original `define` is captured ONCE on the registry itself (SSR_REGISTRY_ORIGINAL_DEFINE): the registry outlives vite dev SSR module re-evaluations, so a second installation must never capture the already-wrapped `define` as its "original" (#1339). - On the dev SSR stub registry (SSR_REGISTRY_STUB_MARKER) re-definition WINS — the registry outlives module re-evaluation, so route edits only reach SSR output when define() overwrites the stale class (#952). - `NotSupportedError` from a non-stub registry is swallowed (the shim's duplicate-define rejection is its designed live-reload notice); any other error propagates. - A tag the entry registered itself (ownership map) is re-registered through the TRUE original define — a dev re-evaluation registers a FRESH class for the SAME tag and the new class must win. A registration the entry did NOT make is a genuine conflict and keeps the fail-closed no-op.

True when the dispatch is an hono/ssg prerender pass. Static build output cannot carry per-request state — the SSG nonce contract (nonce.ts: SSG output carries none, static bytes cannot be per-request) — so the CSP auto-nonce binds nothing on this pass: the handlers' `c.get('cspNonce')` stays undefined and `wrapInDocument` serializes the client script tags nonce-free while the SSG CSP injector writes the policy-only meta.

The subset of

renderLitPageToHtml: (input: { tag: string; props?: Record<string, unknown>; }) => { html: string; } (必填) — `renderLitPageToHtml` — the registered LitElement page host renders to DSD HTML.

Path-derived locale resolution: the first non-empty path segment when it is a declared locale, the fallback otherwise. `locales` is the generated entry's `__locales` project declaration, so request-time resolution and the pages the build emits agree (see expandI18nLocales).

Shell href localization: root-relative hrefs gain the active locale prefix unless they already carry it; locale-neutral, external, and protocol-relative hrefs pass through untouched. Nav data is not part of the 1.0 surface, so the generated `__headerNav` is empty today — the contract keeps its guard.

Merges the loader/action response-header channel into a response. Channel entries are appended after the framework-set headers, so multi-value `Set-Cookie` accumulates; a protocol header ({@linkcode PROTOCOL_HEADERS}) the response already carries is skipped — the channel cannot override the protocol. An empty channel returns the original `Response` object untouched, so responses that never touch the channel keep their identity (and their streaming body is not rebuilt).

headers: Headers (必填) — The **`headers`** read-only property of the Response interface contains the Headers object associated with the response. [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response/headers); ok: boolean (必填) — The **`ok`** read-only property of the Response interface contains a Boolean stating whether the response was successful (status in the range 200-299) or not. [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response/ok); redirected: boolean (必填) — The **`redirected`** read-only property of the Response interface indicates whether or not the response is the result of a request you made which was redirected. [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response/redirected); 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.; statusText: string (必填) — The **`statusText`** read-only property of the Response interface contains the status message corresponding to the HTTP status code in Response.status. [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response/statusText); type: ResponseType (必填) — The **`type`** read-only property of the Response interface contains the type of the response. The type determines whether scripts are able to access the response body and headers. [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response/type); url: string (必填) — The **`url`** read-only property of the Response interface contains the URL of the response. The value of the url property will be the final URL obtained after any redirects. [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response/url); clone: () => Response (必填) — The **`clone()`** method of the Response interface creates a clone of a response object, identical in every way, but stored in a different variable. [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response/clone); body: ReadableStream<Uint8Array<ArrayBuffer>> | null (必填) — [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/body); bodyUsed: boolean (必填) — [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/bodyUsed); arrayBuffer: () => Promise<ArrayBuffer> (必填) — [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/arrayBuffer); blob: () => Promise<Blob> (必填) — [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/blob); bytes: () => Promise<Uint8Array<ArrayBuffer>> (必填) — [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/bytes); formData: () => Promise<FormData> (必填) — [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/formData); json: () => Promise<any> (必填) — [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/json); text: () => Promise<string> (必填) — [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/text)

The subset of the Element serializer the native renderer needs.

renderDsd: (tag: string, options: { componentClass?: unknown; props?: Record<string, unknown>; sourceInfo?: PageSsrSourceInfo; ssrRenderableTags?: readonly string[]; proj… (必填) — Element's sync compiled serializer (`renderDsd`).; customElements: { get(tag: string): unknown; } (必填) — The SSR registry (the runtime's `customElements` global).; ssrRenderableTags: readonly string[] (必填) — Build-admitted nested compiled tags (serialized generated data).

The request-scoped page context the generated handlers build for one render (#1326).

Canonical page-definition extractor: a route module's default export carries the authoring descriptor on `openElementPage`; anything else projects to the empty descriptor. Kept a hoisted-friendly plain function — the generated entry calls it at module evaluation (route registration, routeInfo) and inside every request handler.

The page descriptor a definePage/defineLitPage route module carries on its default export.

The page props projection runtime: the default projection from route params/loader data plus the descriptor's `props`/`error` projector seams. Every seam filters the canonical dangerous-key set (#1214) so hostile params, loader data, or author projector output can never pollute the props record that flows into the compiled serializer.

defaultPageProps: (context: PageContext) => ProjectedProps (必填) — The descriptor-less fallback: params + plain-object loader data.; pageProps: (routeModule: unknown, context: PageContext) => ProjectedProps (必填) — The descriptor `props` projector, falling back to the default projection.; pageErrorProps: (routeModule: unknown, error: unknown, context: PageContext) => ProjectedProps (必填) — The descriptor `error` projector for the error-boundary re-render.

The binding the generated-app factory hands {@linkcode createPagePropsRuntime}.

dangerousKeys: ReadonlySet<string> (必填) — The canonical dangerous-key set (the factory imports it from the kernel-free /authoring leaf): one rule, no second copy.

The generated entry's `__ssr` binding: render one registered host tag to HTML. `depth` bounds nested island expansion; `projectedChildren` claims external content (the app-shell slot). Fails closed per the forks below.

Source metadata the serializer attributes to a render (the `{ route }` seam).

route?: string (可选); source?: string (可选)

Trusted parent-owned light children keyed by slot name (the shell slot claim).

forEach: (callbackfn: (value: TrustedHtmlValue, key: string, map: ReadonlyMap<string, TrustedHtmlValue>) => void, thisArg?: any) => void (必填); get: (key: string) => TrustedHtmlValue (必填); has: (key: string) => boolean (必填); size.toString: (radix?: number) => string (必填) — Returns a string representation of an object.; size.toFixed: (fractionDigits?: number) => string (必填) — Returns a string representing a number in fixed-point notation.; size.toExponential: (fractionDigits?: number) => string (必填) — Returns a string containing a number represented in exponential notation.; size.toPrecision: (precision?: number) => string (必填) — Returns a string containing a number represented either in exponential or fixed-point notation with a specified number of digits.; size.valueOf: () => number (必填) — Returns the primitive value of the specified object.; size.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.; entries: () => MapIterator<[string, TrustedHtmlValue]> (必填) — Returns an iterable of key, value pairs for every entry in the map.; keys: () => MapIterator<string> (必填) — Returns an iterable of keys in the map; values: () => MapIterator<TrustedHtmlValue> (必填) — Returns an iterable of values in the map; __@iterator@4634: () => MapIterator<[string, TrustedHtmlValue]> (必填) — Returns an iterable of entries in the map.

The projected props record handed to the compiled page host.

Headers the loader/action channel may never override once the response already carries them: the framework protocol always wins on conflict. Compared case-insensitively against the channel entry's name; the channel may still introduce one of these when the response does not set it itself.

Native page-tag resolution (#1276, B1.3-F1): the compiled Part Program is the one canonical source for the route→program tag binding. A definePage route module default-exports the compiled page class, whose `__partProgram.tag` carries the

Lit page-tag resolution (#1339 lit fork): a defineLitPage route records its host tag on the class's `openElementPageTag` static (there is no compiled Part Program in the lit path); the path-derived tag stays the fallback.

The per-request response-header channel: the mutable `Headers` instance the loader and the action receive as `context.responseHeaders`, plus the commitment switch the generated stream handler flips when the response is committed.

channel: Headers (必填) — Author-facing view of the channel. Before commitment every `Headers` mutator passes through unchanged; after {@linkcode ResponseHeaderChannel.commit} the mutating methods are gated — a late `append`/`set`/`delete` becomes a warn-and-ignore diagnostic naming the route, header, and operation. It never throws and never mutates the committed response.; commit: () => void (必填) — The header-commitment point: the generated handler calls this once, immediately before it exposes the response body. Later mutator calls are ignored with a diagnostic. Idempotent.

Canonical route metadata derived from a route module: only the keys the entry consumers read (route, layout, title, description), each present exactly when the descriptor defines it — spread-conditional, so an absent key stays absent instead of becoming `undefined`.

A route module namespace as the generated entry imports it (`import * as $route`).

Runs the action POST protocol for one request: resolve the action (named `?/name` map or bare `action` export), enforce the same-origin CSRF floor, parse the form body, classify the outcome, and answer per channel: - fetch callers (`ACTION_FETCH_HEADER: true`) always get JSON — the ActionResult union for outcomes, RFC 9457 problem+json for protocol errors (CSRF 403, unknown action 404, unparseable body 400); - native form callers get PRG 303 on success, the status page on protocol errors, and `{ actionResult }` back for a `fail()` so the handler re-renders the form at the author's status (422).

req: { readonly url: string; readonly raw: Request; header(name: string): string | undefined; } (必填); header: (name: string, value: string) => void (必填); get: (key: string) => unknown (必填); json: (object: unknown, status?: number, headers?: Record<string, string>) => Response (必填); text: (text: string, status?: number, headers?: Record<string, string>) => Response (必填); redirect: (location: string, status?: number) => Response (必填); res: Response (必填) — The response under construction (read by the middleware bridge fallback).

What the generated entry gets from {@linkcode installSsrRegistryGuard}.

register: (tag: string, ctor: unknown) => void (必填) — Registers one component class under `tag` with the same ownership/conflict rules the generated entry has always applied (#952, #1339).

The generated entry's `__statusHtml` binding: title/message rendered into a minimal status page.

The browser installer bootstrap — the inline head script of every streamed page: the MutationObserver that scans streaming templates, the typed seed admission against the same policy budgets the server enforced, the anchor range ownership check, the frame markup safety screen, and the pagehide retirement/BFCache contract. The module owns the string so the server pump and the browser installer read the same constants from one place; S4 will re-home it from the per-page inline form to a shared asset.

Binding-time configuration of {@linkcode createStreamBody}.

escapeAttr: (value: string) => string (必填) — The entry's `escapeAttr` import — an Element function, injected so this module stays free of an Element runtime edge.; timeoutMs.toString: (radix?: number) => string (必填) — Returns a string representation of an object.; timeoutMs.toFixed: (fractionDigits?: number) => string (必填) — Returns a string representing a number in fixed-point notation.; timeoutMs.toExponential: (fractionDigits?: number) => string (必填) — Returns a string containing a number represented in exponential notation.; timeoutMs.toPrecision: (precision?: number) => string (必填) — Returns a string containing a number represented either in exponential or fixed-point notation with a specified number of digits.; timeoutMs.valueOf: () => number (必填) — Returns the primitive value of the specified object.; timeoutMs.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.

The bound streaming body builder the generated handler calls.

Per-request inputs of the streaming body builder.

scope: StreamRequestScope (必填); route: string (必填); manifest: StreamRouteManifest (必填); executor: StreamExecutorView (必填); records: readonly StreamFieldRecord[] (必填); document: StreamDocumentParts (必填); token: string (必填)

The streamed document halves the element `documentStreamParts` produced.

prefix: string (必填); suffix: string (必填)

The slice of the element deferred executor the pump consumes.

shell: string (必填); owner: { readonly instanceId: string; } (必填); seed: Record<string, { type: string; }> (必填); resolvedValue: (field: string, value: unknown) => unknown (必填); serializeResolved: (field: string, value: unknown) => string[] (必填)

One declared deferred field's settlement record (the pump's queue unit).

entry: { field: string; signal: string; owners: Array<{ kind: "part" | "region"; index: number; location: string; source: CompileElementResult["program"]["sourceMap"]… (必填); settled: boolean (必填); failed: boolean (必填); error: unknown (必填); value: unknown (必填); notify?: (() => void) (可选)

The deferred-field front gate: validates the loader data against the route's build manifest (one plain object, the `STREAM_MAX_FIELDS` / `STREAM_MAX_OWNERS` budget, every declared field present, no undeclared thenable), attaches both settlement observers per field, and hands back the records the pump queues. Every rejection first sweeps the loader's own thenables for observation (see {@linkcode observeThenables}).

The request scope the generated handler builds around a streamed route.

request: Request (必填) — The request the loader sees, carrying the scope's abort signal.; upstreamSignal: AbortSignal (必填) — The original WinterCG request's signal (the response-cancel source).; abortWork: () => void (必填) — Aborts the loader's work without tearing down the scope bridge.; cancel: () => void (必填) — Detaches the upstream bridge and aborts the scope (handler-level exit).

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

html: string (必填)

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.

Read the host's `key` slot, initializing it with `init()` on first use.

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)

Overwrite the host's `key` slot.

Read the host's `key` slot, initializing it with `init()` on first use.

Overwrite the host's `key` slot.

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.