API 参考
v1.0.0-alpha.15 的创作面只覆盖 6 个面向使用者的包。已退役的 alpha 包与内部子路径都不是创作面。
创作从产品包开始。
6 个包，一条应用路径。
@openelement/protocol
@openelement/protocol跨系统契约：编译器、运行时与构建共享的 Part Program IR、错误方言与准入描述符（#1557）。
零依赖、仅装契约：章程禁止逻辑在此生长。通常通过转售这些契约的包间接消费。仓库基线——已随 alpha 列车发布。@openelement/element
@openelement/element受支持的 Custom Element 创作面，覆盖 JSX、DSD、hydration、signals 与样式——#1557 拆分后的纯运行时包。
独立的元素创作从这里开始。以 `@element` 装饰的 `OpenElement` 类和 `@property` 状态创作编译元素；`StyleSheet` 与 signal 辅助函数同出包根。@experimental 新增：`element`/`property` 装饰器内在量（#1209）与危险键守卫 `isDangerousKey`、`injectPropsSafe`、`DANGEROUS_KEYS`（#1214）。@openelement/compiler
@openelement/compiler构建期 TSX-to-Part-Program 编译器及其 Vite 插件边界；唯一携带 TypeScript 依赖的包（#1557）。
仅构建期工具——绝不进入浏览器/运行期依赖图。通常通过 `@openelement/router` 构建驱动；独立插件在 `@openelement/compiler/vite`。仓库基线——已随 alpha 列车发布。@openelement/router
@openelement/router应用与构建面：页面、路由、island、请求/渲染语义、Vite 集成、静态生成与 Nitro 输出。
用 `definePage` 与 `defineIslandConfig` 进行应用创作。构建使用 `@openelement/router/vite` 的 `openPipeline()`/`openElement()` 或生成的构建任务。插件顺序、manifest 与内容扫描属于 router 的实现细节。@openelement/create
@openelement/create安装即用的 starter，零上下文的使用者入口。
生成的项目暴露 `dev`、`check`、`test`、`build`、`start` 与 `preview`。starter 只导入产品包。@openelement/ui
@openelement/ui可选原语，仅在已证明行为可复用时保留。
使用 OpenElement 不依赖 UI 包。网站特有的品牌、hero、lab 与布局工件不属于 UI 包的契约。每一个记录在案的导出，都有锚点。
@openelement/protocol
431 个导出Route action: handles form submissions for a page route.
Action<T, Env, Platform, 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.
"x-openelement-action"Context passed to a route action function (extends loader context).
ActionContext<Env, Platform, 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). Success carries no data envelope. The application-loop contract makes a successful non-GET action answer 303 (PRG) — the framework never answers 200 with a rendered page, or with a success document, for a successful mutation — so the fetch channel answers `{ type: 'redirect' }` naming the PRG target and the authored return value is discarded by design. Success data travels the PRG target instead (query state the loader re-runs with, which the props projector then maps; see the router guide's "Form actions" section). The union previously declared a `{ type: 'success' }` member that no code path ever emitted — removed so the type matches the wire. 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.
ActionResult<Failure>One API route declaration in the generated entry descriptor.
ApiRouteDeclAttribute/authoring-surface failures (phase `validation`).
{ readonly INVALID_TAG_NAME: "OE_INVALID_TAG_NAME"; readonly UNSAFE_META_ATTRIBUTE: "OE_UNSAFE_META_ATTRIBUTE"; readonly UNSAFE_ATTRIBUTE_NAME: "OE_UNSAFE_ATTRIBUTE_NAME"; readonly UNSAFE_URL_SINK: "OE_UNSAFE_URL_SINK";…Result returned by the OpenElement build pipeline.
BuildArtifactsA single client asset emitted by the build pipeline.
BuildClientAsseti18n configuration for the build pipeline.
BuildI18nOptionsA single island input to the build pipeline.
BuildIslandInputManifest produced by the build pipeline.
BuildManifestArtifactOutput configuration for the build pipeline.
BuildOutputOptionsPackage island configuration for the build pipeline.
BuildPackageIslandOptionsA single generated HTML page artifact.
BuildPageArtifactFramework-agnostic plan consumed by the OpenElement build pipeline.
BuildPlanA single route input to the build pipeline.
BuildRouteInputThe one camelCase → kebab-case casing rule for custom-element attribute names, so `<x-el itemCount={5}>` round-trips as `item-count` on every boundary that derives an attribute name from a prop name: the compiler's property metadata, the SSR serializer, and the client attribute handling.
(str: string): stringThe compatibility classification report for one custom element manifest.
CemCompatibilityReportOne property entry of the compiled custom-elements-manifest metadata.
CemPropertyMetadataClaim failures: the existing DOM does not match the program that would own it. The value shipped in 1.0.0-alpha.3 and is kept verbatim; consumers match on it, and `PartProgramHydrationError` is its only raiser.
{ readonly STRUCTURE_MISMATCH: "OPEN_ELEMENT_COMPILED_CLAIM_MISMATCH"; readonly PRE_UPGRADE_EVENTS_INVALID: "OE_CLAIM_PRE_UPGRADE_EVENTS_INVALID"; readonly DYNAMIC_NODE_IN_STATIC_REGION: "OE_CLAIM_DYNAMIC_NODE_IN_STATIC…The Phase 2 client build's delivery manifest, keyed by island identity.
ClientAssetManifestThe client asset one compile-time island identity resolves to.
ClientIslandAssetClient island entry shape passed to entry generator.
ClientIslandEntryThe 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.
CompatibilityClassificationHow 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.
CompatibilityTierVersion of the compiled-module ABI: the statics a generated module carries (`__partProgram`, `__compiledProperties`, `__elementMetadata`, `__observedAttributes`, `__computedFields`) and the runtime facade binds. Bump when the generated-module contract changes shape; generated artifacts stamp both this and PART_PROGRAM_VERSION so consumers can tell format drift from release drift. v2: platform lifecycle callback bodies are emitted inside a boundary-capture wrapper calling the base class's `_captureError` — a generated module now requires a runtime facade carrying that protected method (the v1 shape emitted the bodies verbatim).
2The compiled custom-elements-manifest metadata block of one component.
CompiledCemMetadataThe compiled element metadata the program carries for tooling consumers.
CompiledElementMetadataOne compiled
CompiledPropertyMetadataCompiler (build-time) failures. The per-diagnostic `OEC####` codes stay on each diagnostic; these classify the family so a build failure is catchable as one thing.
{ readonly DIAGNOSTICS: "OE_COMPILER_DIAGNOSTICS"; readonly INVALID_SOURCE: "OE_COMPILER_INVALID_SOURCE"; }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.
ComponentLayerOperator/literal compatibility for when-Block tests (issue #1372). Both wire validators (this module and the server serializer's shared validator) close the space through this one predicate: - ordering operators require a finite numeric literal; - `equals`/`not-equals` admit a finite number, string, or boolean; - `truthy` admits exactly `true` or `false` (the recorded expectation).
(op: unknown, value: unknown): booleanThe comparison operators a program condition supports.
ConditionOperatorCommunity-context service lifecycle failures (phase `csr`).
{ readonly SERVICE_DISPOSED: "OE_CONTEXT_SERVICE_DISPOSED"; }The CORS origin policy an API route declares.
CorsOriginConfigThe content-security-policy directives a route or document declares.
CspConfigInternal SSR provenance marker on light-mode host tags (#1148). Present only when the host's light subtree was server-rendered under the in-place activation contract: the client binds the existing DOM instead of clearing it, and a parent's activation walk prunes the nested host's subtree. Client rendering never writes it and it is never removed. The writer (internal/compiled/server) and readers (internal/compiled/runtime) import this constant; nothing writes the literal.
"data-oe-light"Default code for {@linkcode RenderError }. Deliberately NOT a member of {@linkcode ErrorCode}: that object is the scan target of the documentation site's error catalog, which requires every member to carry a phase/severity family rule. `RENDER_ERROR` is the pre-dialect value `RenderError` has always defaulted to — kept verbatim so callers that observe it keep working, and kept out of the catalogue because it is not a failure this package classifies, only a constructor default a caller may override.
"RENDER_ERROR"The `format` discriminator every report carries. Consumers branch on it instead of guessing: a future shape change mints a new tag rather than reinterpreting old bytes.
"openelement.diagnostics/1"One machine-readable diagnostic: the producer's stable code, where the failure sits (`file`, `line`, `column` — absent when the producer has no source location, e.g. a configuration refusal), what happened (`message`), and when known, the fix (`hint`). `line`/`column` are 1-based, matching the diagnostics the compiler records from TypeScript source positions. Unknown envelope fields are tolerated on the wire (forward compat); the required core is exactly these fields.
DiagnosticEnvelopeThe pipeline phase a diagnostic was raised in — the same vocabulary the error contract's {@linkcode ErrorPhase } uses, so a producer's code, phase and envelope cannot disagree about where a failure happened.
DiagnosticPhaseAssemble the exit's report. `ok` derives from the diagnostics' severities, never from a caller's optimism: one `error` severity is enough to fail it.
(diagnostics: DiagnosticEnvelope[]): DiagnosticReportOne build exit's diagnostics: the format tag, whether the run is clean (`ok` is false the moment any diagnostic carries severity `error`), and every diagnostic the exit collected. This is the document the CLI writes to the stream and the diagnostics file — one aggregate containing every code.
DiagnosticReportOne format tag value (kept as a type for the report's `format` field).
"openelement.diagnostics/1"Raised by {@linkcode parseDiagnosticReport} when the text is not a consumable report. Fail closed: a consumer that catches this knows the channel answered garbage — never a half-valid report.
class DiagnosticReportParseError extends ErrorHow severe one diagnostic is. `error` fails the build, `warning` reports a recoverable defect, `info` is reserved for advisories. The build report's `ok` flag derives from this: any `error` diagnostic makes the report not-ok.
DiagnosticSeverityThe document-level facts a build bakes into the generated entry.
DocumentConfigKeyed-list identity failures. Shared by the server serializer and the client runtime (see `internal/compiled/each-key.ts`), so both executors reject the same data with the same code.
{ readonly ITEM_NOT_A_RECORD: "OE_EACH_ITEM_NOT_A_RECORD"; readonly KEY_NOT_ROUND_TRIPPABLE: "OE_EACH_KEY_NOT_ROUND_TRIPPABLE"; readonly DUPLICATE_KEY: "OE_EACH_KEY_DUPLICATE"; }The manifest a project without a client bundle carries.
ClientAssetManifestProperty on the stub holding the generated entry's registration-ownership map (tag -> class it registered): a route module that self-registers its tag wins over the entry's registration, and on dev re-evaluation a fresh self-registered class must still win (#952).
"__openEntryDefined"The full build-time description of one generated entry: routes, islands, renderers, middleware, document, and layout plans.
EntryDescriptorError message prefix for all openElement errors.
"[openElement]"Well-known error code constants for reference. String values are always accepted.
{ readonly SSR_RENDER_ERROR: "SSR_RENDER_ERROR"; readonly BOUNDARY_CAUGHT: "BOUNDARY_CAUGHT"; readonly UNKNOWN: "UNKNOWN"; }The pipeline phase an error was raised in.
ErrorPhaseHow severe a framework error is.
ErrorSeverityCallback receiving every reported {@linkcode OpenElementError} for telemetry.
ErrorTelemetryHookMap the one error dialect ({@linkcode OpenElementError} — every producer's raiser goes through it) onto the envelope. The error's code, severity and phase ARE the envelope's; the message carries verbatim. Producers with a fix pass it as `hint`.
(error: OpenElementError, options?: { hint?: string; }): DiagnosticEnvelopeSSR/bootstrap failures raised by the public entries (phase `ssr` / `csr`).
{ readonly PROGRAM_MISSING: "OE_PROGRAM_MISSING"; readonly COMPOSITION_DEPTH: "OE_SSR_COMPOSITION_DEPTH"; readonly COMPUTED_FACTORY_MISSING: "OE_COMPUTED_FACTORY_MISSING"; readonly COMPUTED_READONLY: "OE_COMPUTED_READON…Forbidden sink names — the ONE canonical deny list for every Part Program boundary: the compiler semantic core, the protocol validator (internal/protocol/part-program.ts), and the compiled server/claim validator (internal/compiled/server/shared.ts). This module is import-free and host-free by design (same base-of-graph contract as void-tags.ts): all consumers import it, so a new forbidden sink cannot be enforced on one boundary and missed on another. This module owns the named-sink deny lists and the attribute-name policy built on them (the one shared safe-attribute-name predicate and the one camelCase→kebab-case casing rule); consumers delegate so the boundary cannot diverge. The lists are fail closed and case-insensitive (attribute and property names are compared lowercase, matching the HTML parser's name folding): - `FORBIDDEN_ATTRIBUTE_NAMES`: attribute names that must never be a static attribute or an `attr`/`bool` sink. `srcdoc` smuggles a full HTML document past attribute escaping; `innerHTML` is admissible only through the dedicated trusted-HTML `html` Part, never as a plain attribute name. - `FORBIDDEN_PROPERTY_NAMES`: `prop` sink names that would re-prototype or re-construct the target element (prototype-pollution primitives). - `RAW_TEXT_TAGS`: raw-text elements are outside the compiled grammar — their content cannot be escaped by the serializer.
ReadonlySet<string>Property names the compiler refuses as
ReadonlySet<string>Sink categories the canonical deny list classifies.
ForbiddenSinkKindReturn a human-readable reason when `name` is a forbidden sink of `kind`, or null when the name is admissible. Unknown kinds fail closed with a reason instead of being waved through.
(kind: ForbiddenSinkKind, name: string): string | nullOne framework failure: {@linkcode OpenElementError} with the caller's code and the phase/severity/recoverability that phase implies. Every throw site in this package goes through this factory (or the `*ErrorCode` tables above) so a code, a phase and a recoverability answer cannot drift per site.
(code: string, message: string, options?: Omit<OpenElementErrorOptions, "code">): OpenElementErrorThe adapter-facing framework options: where routes and islands live, which renderer serializes pages, the default layout and named-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.
FrameworkOptionsRuntime 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.
readonly ["load", "idle", "visible", "only", "none"]The hydration delivery hint a component or route carries.
HydrationHintIsland hydration trigger: 'load' | 'idle' | 'visible' | 'only'.
"load" | "idle" | "visible" | "only" | "none"Idle-hydration scheduling fallback (milliseconds) when neither `requestIdleCallback` nor `requestAnimationFrame` is available.
50One module import the generated entry emits.
ImportDeclThe wire-validator face of the one canonical attribute-name predicate (delegates to `./forbidden-sinks.ts`); exported for parity tests.
(value: unknown): value is stringThe static-sidecar descriptor router injects into the element compiler.
StaticSidecarDescriptorOne island the build admits: tag, module path, and delivery facts.
IslandDeclAdapter-owned browser delivery strategy, including media-query admission.
IslandDeliveryStrategyShared island module identity (CL-3 convergence: one base, three shapes). Every island record names the same module the same way — the tag it registers as, the module path that owns it, and whether that module is a package (CEM-derived named export) rather than a local file (default export) — so a rename of the identity touches one declaration, not three. The delivery-strategy fields intentionally stay per-shape (`strategy` on the client entry vs `hydrate` on the build decls): they are different stages' vocabularies, not one field spelled two ways.
IslandModuleIdentityPer-island delivery options (hydration strategy, SSR/DSD participation).
IslandOptionsOptions for the build-time island source transform.
IslandTransformOptionsThe island transform output: rewritten source plus extracted facts.
IslandTransformResultThe one safe-attribute-name predicate (#1033, #602). Attribute *names* are not escaped on any render path, so a name must be valid HTML attribute-name grammar (blocks quote/space injection), must not be an event handler (`on*`, case-insensitive), and must not be a forbidden sink (`innerhtml`/ `srcdoc` — case-insensitive). Every boundary that admits an attribute name — the compiler semantic core, the Part Program validator, the compiled server validator, and the SSR head/meta name checks — delegates here, so the rules cannot diverge per path.
(name: string): booleanAn event binding scoped to each item of an `each` block. The runtime attaches this listener to every item root node created by the block, making per-item handlers (onClick={this.select(row.id)}) expressible without fixed-path event parts.
ItemEventBindingElement-lifecycle failures: the kernel was driven outside its contract (phase `csr`).
{ readonly DISPOSED: "OE_KERNEL_DISPOSED"; readonly TAG_MISMATCH: "OE_KERNEL_TAG_MISMATCH"; readonly CLAIM_EXECUTOR_MISSING: "OE_KERNEL_CLAIM_EXECUTOR_MISSING"; readonly ROOT_NOT_OWNED: "OE_KERNEL_ROOT_NOT_OWNED"; reado…Layout declaration: `false` disables the layout entirely, `'default'` uses the built-in layout, 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 layout properties the router injects per route.
LayoutConfigThe layout module a build resolves: tag, import path, and serialized props.
LayoutDeclThe resolved layouts a build ships: the default layout plus named layouts.
LayoutPlanRoute loader: fetches data for a page route.
Loader<T, Env, Platform, Route>Context passed to a request-time ('dynamic') route loader.
LoaderContext<Env, Platform, Route>Locale-aware resolved path contract.
LocalePathRequest-body bound (bytes) the generated entry applies to action POST routes; larger uploads belong on API routes with explicit limits.
numberNested element expansion depth bound for `renderToString`: cyclic component composition fails closed instead of recursing without end.
8Fetch 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.
MiddlewareOne middleware module the generated entry composes.
MiddlewareDeclThe scope one middleware applies to (all routes or a named route set).
MiddlewareScopeDeclOne 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).
ModuleVocabularyDescriptorOne documented attribute of a custom element declaration.
OpenElementAttributeBlog options stored in the build context by
OpenElementBlogOptionsMinimal build context interface that sub-plugins can use.
OpenElementBuildContextLikeOne documented CSS part of a custom element declaration.
OpenElementCssPartOne custom element declaration in a package manifest: tag, members and delivery metadata.
OpenElementDeclarationFramework error carrying a stable code, severity, phase and recoverability contract.
class OpenElementError extends ErrorConstructor options for {@linkcode OpenElementError}; every field is defaulted.
OpenElementErrorOptionsOne documented custom event of a custom element declaration.
OpenElementEventThe openElement-specific extension block of a package manifest declaration.
OpenElementExtensionsi18n options stored in the build context by
OpenElementI18nContextOptionsPackage manifest of component declarations (not a Custom Elements Manifest).
OpenElementPackageManifestThe host-neutral request handler every runtime adapter and generated server entry exposes: a WinterCG `(request, context?) => Response` with no server engine dialect baked in.
OpenElementRequestHandler<Env>Host-agnostic route and asset contracts shared by app and build drivers.
OpenElementRouteKindOne 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`.
OpenElementRouteNodeOne documented slot of a custom element declaration.
OpenElementSlotA declaration's utility-compilation requirement and the package-owned style sources that requirement compiles (the declared-compilation contract; see the router's `style-plan` module for the resolution rules). `required` is the mandatory-compilation dependency: the component's presentation cannot be delivered without the compile, so an application that disables the entry (`tailwind: false`) fails the build with a coded diagnostic instead of shipping an unstyled component. Merely offering a theme source is NOT a requirement — leave `required` unset for a source a consumer may adopt on its own. `sources` are package-relative paths (e.g. `./theme.css`) resolved against THIS package, so a consumer never repeats the owner's declaration. They must exist in the installed package (i.e. ship in the tarball). `dialect` names the CLASS LANGUAGE this component's utility tokens are written in, not the engine that compiles them: the declaration stays provider-neutral, and a selected provider that does not implement the dialect fails the build before any compile. Omitted means `tailwind4` — the language every declaration written before this field existed uses.
OpenElementTailwindDeclarationOne page route declaration in the generated entry descriptor.
PageRouteDeclParse one report off the wire. Fails closed: truncated JSON, a foreign format tag, or any structurally broken diagnostic raises {@linkcode DiagnosticReportParseError} instead of returning a partial report a consumer might mistake for the truth.
(text: string): DiagnosticReportThe Part Program IR version this package defines (currently v2).
2The comment marker closing a part anchor in serialized program markup.
(index: number): stringAnchor marker payloads shared by seed runtime consumers.
(index: number): stringThe serializable Part Program v2: one compiled component as data.
PartProgramV2The one deterministic program consumed by all execution modes.
PartProgramV2Media type of the RFC 9457 action error channel (#863).
"application/problem+json"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.
ProblemDetailsString attribute sink bound to a Signal.
ProgramAttrPartOne block the program tracks: the boundaries of a dynamic subtree.
ProgramBlockRecordBoolean attribute sink bound to a Signal.
ProgramBoolPartSpecialized fixed sinks make ownership explicit for class and style text.
ProgramClassPartOne condition clause of a when part.
ProgramConditionOne module dependency the compiled module graph records.
ProgramDependencyRecordA list part: repeats its template node per item of a bound signal.
ProgramEachPartA static element node of the program tree.
ProgramElementNodeProgram-shape failures: a Part Program (or one of its records) is malformed, or carries a value the wire format cannot express. Phase `validation`: these reject data before any DOM work starts.
{ readonly INVALID_PROGRAM: "OE_PROGRAM_INVALID"; readonly NOT_SERIALIZABLE: "OE_PROGRAM_NOT_SERIALIZABLE"; readonly INVALID_SLOT: "OE_PROGRAM_INVALID_SLOT"; readonly INVALID_SOURCE_SEGMENT: "OE_PROGRAM_INVALID_SOURCE_S…The action one event part dispatches.
ProgramEventActionAn event binding part: listener wiring between DOM event and action.
ProgramEventPartTrusted-HTML content sink (alpha.9). The signal value must carry the runtime TrustedHtml capability; its HTML replaces the target element's content. The target's subtree is opaque to the claim path. The compiler emits this only for an explicit `innerHTML={this.<field>}` sink on an otherwise childless element — there is no implicit or discovery path to raw HTML.
ProgramHtmlPartItem-value text slot; valid only inside an `each` item template. `field` names the item field rendered by this slot — multi-field item templates carry one slot per field, and the compiler always emits it.
ProgramItemValueNodeExact compiler-owned location for one dynamic sink or range anchor.
ProgramLocationA location record also makes the identity auditable without inspecting parts.
ProgramLocationRecordThe discriminated union of dynamic parts a program instantiates.
ProgramPartThe anchor node marking where a part binds in the tree.
ProgramPartAnchorNodeWhere a part sits relative to its anchor.
ProgramPositionDOM property sink bound to a Signal; `path` is retained for seed consumers.
ProgramPropPartA named ref slot is serializable; the generated class supplies the ref value.
ProgramRefPartThe root of one program tree: element, part anchor, or text.
ProgramRootThe kind of source record a program source map entry carries.
ProgramSourceKindThe program source map: authored spans projected onto emitted records.
ProgramSourceMapA half-open [start, end) range into the authored source text.
ProgramSourceRangeOne source-map record: the authored origin of one emitted node or part.
ProgramSourceRecordA style binding part.
ProgramStylePartA static text node of the program tree.
ProgramTextNodeA text interpolation part bound to one signal.
ProgramTextPartThe discriminated union of static tree nodes.
ProgramTreeNodeA conditional part: swaps template branches on a condition.
ProgramWhenPartThe serialized value-type tag of a compiled property default.
PropertyValueTypeRaise one framework failure and never return: the throwing companion of {@linkcode frameworkError}. The per-module `fail(code, message)` micro-factories bind their failure surface's fixed {@linkcode ErrorPhase} here — one implementation, the phase as a parameter — so a code and a phase cannot drift apart per throw site.
(phase: ErrorPhase, code: string, message: string): neverElements whose text content must never be interpolated as markup.
ReadonlySet<string>Read-only signal protocol used by computed values.
ReadonlySignal<T>One page renderer module registration.
RendererDeclOne render failure record the SSR pipeline reports.
RenderErrorThe resolved layout for one plan slot: disabled (false) or a full declaration.
ResolvedLayoutHow the compiled component attaches its root: light DOM or a shadow root.
RootModeOne 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.
RouteEntryA single route metadata entry emitted as `routeInfo` by the generated SSG entry module (see entry-render-ssg.ts).
RouteInfoEntryThe module vocabulary router injects into `analyzeModuleSemantics`.
readonly ModuleVocabularyDescriptor[]Whether the authored error prose is kept: `true` everywhere except a production client build, the one context that defines `OE_RUNTIME_MESSAGES` to `false`. Stripping is a payload decision, so it belongs to the browser bundle only — server-side failures keep their prose.
booleanA host runtime adapter: exposes the fetch handler a server engine dispatches to.
RuntimeAdapter<Env>Options one runtime adapter is constructed with.
RuntimeAdapterOptions<Env>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.
RuntimeContext<Env>Runtime execution failures raised while a compiled program is serialized, built into fresh DOM, or re-read on a signal write (phase `render`).
{ readonly LIST_VALUE_NOT_ARRAY: "OE_RUNTIME_LIST_VALUE_NOT_ARRAY"; readonly HOST_SIGNAL_MISSING: "OE_RUNTIME_HOST_SIGNAL_MISSING"; readonly HOST_HANDLER_MISSING: "OE_RUNTIME_HOST_HANDLER_MISSING"; readonly HOST_REF_MIS…Branded type: a string that has been HTML-escaped (safe for text content)
SafeHtmlThe JSON-serializable value shape a compiled property default admits.
SerializableValueSerialize the manifest as the generated dist/server/client-assets.js module: pure structured data, no injection logic — consumers derive what they need from these values.
(manifest: ClientAssetManifest): stringSerialize a report for the stream/file channel: one line, no trailing newline.
(report: DiagnosticReport): stringCompiled server/claim validation failures. The value shipped in 1.0.0-alpha.3 and is kept verbatim; `CompiledProgramValidationError` is its only raiser.
{ readonly PROGRAM_INVALID: "OPEN_ELEMENT_COMPILED_PROGRAM_INVALID"; readonly SINK_REFUSED: "OE_SERVER_SINK_REFUSED"; }Canonical request-time/SSG server route context.
ServerRouteContext<Env, Platform, 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().
ServerRouteMetadataAlias for APIs that accept either writable or read-only signals.
Signal<T>Runtime/type brand for signals created by the configured reactive engine.
typeof SIGNAL_BRANDSignal engine protocol used by the framework's built-in adapter. This is a deliberate internal seam, not a public compatibility contract: the framework layer talks to signals only through this narrow interface so its call sites stay implementation-agnostic. The package ships and verifies exactly one engine implementation (`preact-engine`, backed by `@preact/signals-core`). Preact's own API is not Element public API, and arbitrary third-party engines are not promised; any future engine would be added behind this protocol rather than inline (charter decision — see #723).
SignalEngineMinimal signal-like object accepted by renderers and bindings.
SignalLike<T>Special file kinds the route scanner recognizes by filename: `renderer` and `middleware`.
SpecialFileTypeSpeculation Rules configuration for SSG post-processing
SpeculationRulesOptionsUser-facing SSG build behavior switches (OpenElementOptions['ssg']).
SsgBehaviorOptionsPer-page render diagnostics returned by renderRoute()
SsgPageOutputThe per-build render evidence record the SSG engine emits for audit.
SsgRenderEvidenceOptions passed to the shared SSG render pipeline.
SsgRenderOptionsSummary of an SSG render run, returned by ssgRender().
SsgRenderSummaryProperty on the SSR registry holding the TRUE original `define` method, captured before the generated entry installs its idempotent wrapper. The registry outlives vite dev SSR module re-evaluations, so without this the second evaluation would capture the already-wrapped `define` as its "original" and every forced re-registration would silently early-return through the previous wrapper (#1339 lit dev feedback).
"__openElementOrigDefine"Marker property set to `true` on the SSR customElements stub. Readers must treat the marked registry as re-definable.
"__openElementSsrStub"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.
SsrAdmissionDecisionThe build-time SSR admission decisions per component tag.
SsrAdmissionPlanThe server bundle facts the SSG engine consumes for stream rendering.
SsrBundleThe one `<style>` element the server serializer emits as the first DSD template child when the class carries static styles (renderToString parity — pages never upgrade, so their styles must ship in the payload). The claim path skips exactly this marked node; a marked node on a style-less class is claim drift and fails closed.
"data-oe-static-styles"Build-host-only compiled component reached through a route's local import graph. These components participate in recursive SSR/SSG expansion but are not client islands and therefore add no hydration or browser entry.
StaticComponentDeclOne static-sidecar descriptor the host injects into the element compiler: the admission granted is a colocated static policy statement (#1473 item 3, the static-sidecar admission pattern).
StaticSidecarDescriptorWhere an island's resolved hydration strategy came from.
StrategySourceTags a deferred frame cannot safely install into an owned Part range: the browser installer rejects any frame whose markup carries one of these.
readonly ["script", "style", "template", "iframe", "object", "embed", "base", "meta", "link"]Schemes that make a URL attribute unsafe in a streamed frame.
RegExpURL-carrying attributes the frame check screens for script-bearing scheme obfuscation; only these attribute names are value-screened.
readonly ["href", "src", "action", "formaction", "xlink:href"]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.
32Deferred 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.
32Part/Block owners one stream route's manifest may address in total across all deferred fields.
64Serialized 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.
numberTyped 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.
64Deferred-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.
30000Build-only route projection bound to a specific compiled page program.
StreamRouteManifestThe one key marking a sheet whose bytes are a LIVE resource rather than an immutable one (alpha15 S lane, S-C1.3). The dev server serves an authored sheet from a mutable endpoint that hot-updates: the sheet object is the copy the live resource re-fills through `replace()`, so every root that adopted it re-renders on an edit. A root whose serialized markup declares the same URL therefore still ADOPTS this sheet — the declarative `<link>` stays the first-paint / no-JavaScript delivery, and the adopted object is the one an edit reaches. Without that, a CSS-only edit could only be delivered by re-fetching the link, which is a DOM write this protocol does not perform. Production sheets never carry this key: their URL is content-addressed, so the link and the sheet can never disagree and one delivery is the whole story. Build-time and runtime cannot drift because the dev adapter generator interpolates this exact name.
"__openElementStyleSheetLive"The one key under which a sheet carries its readiness promise: the generated client style adapter records it on the sheet it exports, and the element runtime reads the same key to hand styles to roots that are already connected. Build-time and runtime cannot drift because the adapter generator interpolates this exact name. The promise settles once. Fulfillment means the rules were installed through `replace()`; rejection carries the load or replacement failure and keeps its rejected state — an observer may attach its own catch, it must never convert the promise into a fulfilled one.
"__openElementStyleReady"The one key under which a sheet carries the URL of the external CSS resource that delivers its rules: the generated client style adapter records the emitted asset URL on the sheet it exports, and the element runtime compares it against the declarative `<link rel="stylesheet" data-oe-static-styles>` nodes an SSR/DSD template already carries (alpha15 S lane). A root whose serialized markup already references the sheet's URL keeps that link as the delivery and does NOT adopt a second constructable copy — one stylesheet resource, one delivery, no duplicate application. Build-time and runtime cannot drift because the adapter generator interpolates this exact name.
"__openElementStyleSheetUrl"Compiled-style application failures (phase `csr`).
{ readonly ADOPTED_STYLES_UNSUPPORTED: "OE_STYLES_ADOPTED_STYLES_UNSUPPORTED"; readonly SHEET_LOAD_FAILED: "OE_STYLES_SHEET_LOAD_FAILED"; readonly INVALID_STYLE_HREF: "OE_STYLES_INVALID_HREF"; readonly SHEET_RULES_UNREA…Minimal stylesheet contract (replaceSync + cssRules) satisfied by native and shim sheets.
StyleSheetLikeCross-environment CSSStyleSheet abstraction. In browsers this delegates to the native CSSStyleSheet API. In SSR runtimes it falls back to a minimal in-memory implementation that exposes the subset used by OpenElement and renderToString().
StyleSheetRuleBranded type: a string that is intentionally raw/untrusted HTML
UnsafeHtmlWhether 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.
(name: string, value: string): booleanUnsubscribe function returned by subscriptions and effects.
UnsubscribeValidate an unknown value as a Part Program v2. The validator is intentionally strict: unknown instruction kinds, missing ownership records and unsafe paths fail before a runtime can guess at their meaning.
(raw: unknown): asserts raw is PartProgramHTML void elements — the ONE canonical tag set for every serializer, validator, and compiler in the workspace (issue #1220, M4). This module is import-free and host-free by design: it sits at the base of the module graph so the DOM runtime (internal/core/html-escape.ts), the Part Program exchange artifact (internal/protocol/part-program.ts), and the compiler semantic core can all consume the same definition without an import cycle or a second source of truth. Content is the full HTML Standard void-element list, `param` included. Do not redefine this set anywhere else; internal/core/html-escape.ts and internal/protocol/part-program.ts re-export it, and __tests__/void-tags-convergence.test.ts enforces the single owner.
ReadonlySet<string>Writable signal protocol used by openElement integrations.
WritableSignal<T>Host-agnostic route and asset contracts shared by app and build drivers.
OpenElementRouteKindOne 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`.
OpenElementRouteNodeThe Phase 2 client build's delivery manifest, keyed by island identity.
ClientAssetManifestThe client asset one compile-time island identity resolves to.
ClientIslandAssetThe manifest a project without a client bundle carries.
ClientAssetManifestSerialize the manifest as the generated dist/server/client-assets.js module: pure structured data, no injection logic — consumers derive what they need from these values.
(manifest: ClientAssetManifest): stringRoute action: handles form submissions for a page route.
Action<T, Env, Platform, 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.
"x-openelement-action"Context passed to a route action function (extends loader context).
ActionContext<Env, Platform, 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). Success carries no data envelope. The application-loop contract makes a successful non-GET action answer 303 (PRG) — the framework never answers 200 with a rendered page, or with a success document, for a successful mutation — so the fetch channel answers `{ type: 'redirect' }` naming the PRG target and the authored return value is discarded by design. Success data travels the PRG target instead (query state the loader re-runs with, which the props projector then maps; see the router guide's "Form actions" section). The union previously declared a `{ type: 'success' }` member that no code path ever emitted — removed so the type matches the wire. 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.
ActionResult<Failure>Route loader: fetches data for a page route.
Loader<T, Env, Platform, Route>Context passed to a request-time ('dynamic') route loader.
LoaderContext<Env, Platform, Route>Media type of the RFC 9457 action error channel (#863).
"application/problem+json"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.
ProblemDetailsCanonical request-time/SSG server route context.
ServerRouteContext<Env, Platform, 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().
ServerRouteMetadataThe `format` discriminator every report carries. Consumers branch on it instead of guessing: a future shape change mints a new tag rather than reinterpreting old bytes.
"openelement.diagnostics/1"One machine-readable diagnostic: the producer's stable code, where the failure sits (`file`, `line`, `column` — absent when the producer has no source location, e.g. a configuration refusal), what happened (`message`), and when known, the fix (`hint`). `line`/`column` are 1-based, matching the diagnostics the compiler records from TypeScript source positions. Unknown envelope fields are tolerated on the wire (forward compat); the required core is exactly these fields.
DiagnosticEnvelopeThe pipeline phase a diagnostic was raised in — the same vocabulary the error contract's {@linkcode ErrorPhase } uses, so a producer's code, phase and envelope cannot disagree about where a failure happened.
DiagnosticPhaseAssemble the exit's report. `ok` derives from the diagnostics' severities, never from a caller's optimism: one `error` severity is enough to fail it.
(diagnostics: DiagnosticEnvelope[]): DiagnosticReportOne build exit's diagnostics: the format tag, whether the run is clean (`ok` is false the moment any diagnostic carries severity `error`), and every diagnostic the exit collected. This is the document the CLI writes to the stream and the diagnostics file — one aggregate containing every code.
DiagnosticReportOne format tag value (kept as a type for the report's `format` field).
"openelement.diagnostics/1"Raised by {@linkcode parseDiagnosticReport} when the text is not a consumable report. Fail closed: a consumer that catches this knows the channel answered garbage — never a half-valid report.
class DiagnosticReportParseError extends ErrorHow severe one diagnostic is. `error` fails the build, `warning` reports a recoverable defect, `info` is reserved for advisories. The build report's `ok` flag derives from this: any `error` diagnostic makes the report not-ok.
DiagnosticSeverityMap the one error dialect ({@linkcode OpenElementError} — every producer's raiser goes through it) onto the envelope. The error's code, severity and phase ARE the envelope's; the message carries verbatim. Producers with a fix pass it as `hint`.
(error: OpenElementError, options?: { hint?: string; }): DiagnosticEnvelopeParse one report off the wire. Fails closed: truncated JSON, a foreign format tag, or any structurally broken diagnostic raises {@linkcode DiagnosticReportParseError} instead of returning a partial report a consumer might mistake for the truth.
(text: string): DiagnosticReportSerialize a report for the stream/file channel: one line, no trailing newline.
(report: DiagnosticReport): stringAttribute/authoring-surface failures (phase `validation`).
{ readonly INVALID_TAG_NAME: "OE_INVALID_TAG_NAME"; readonly UNSAFE_META_ATTRIBUTE: "OE_UNSAFE_META_ATTRIBUTE"; readonly UNSAFE_ATTRIBUTE_NAME: "OE_UNSAFE_ATTRIBUTE_NAME"; readonly UNSAFE_URL_SINK: "OE_UNSAFE_URL_SINK";…Claim failures: the existing DOM does not match the program that would own it. The value shipped in 1.0.0-alpha.3 and is kept verbatim; consumers match on it, and `PartProgramHydrationError` is its only raiser.
{ readonly STRUCTURE_MISMATCH: "OPEN_ELEMENT_COMPILED_CLAIM_MISMATCH"; readonly PRE_UPGRADE_EVENTS_INVALID: "OE_CLAIM_PRE_UPGRADE_EVENTS_INVALID"; readonly DYNAMIC_NODE_IN_STATIC_REGION: "OE_CLAIM_DYNAMIC_NODE_IN_STATIC…Compiler (build-time) failures. The per-diagnostic `OEC####` codes stay on each diagnostic; these classify the family so a build failure is catchable as one thing.
{ readonly DIAGNOSTICS: "OE_COMPILER_DIAGNOSTICS"; readonly INVALID_SOURCE: "OE_COMPILER_INVALID_SOURCE"; }Community-context service lifecycle failures (phase `csr`).
{ readonly SERVICE_DISPOSED: "OE_CONTEXT_SERVICE_DISPOSED"; }Default code for {@linkcode RenderError }. Deliberately NOT a member of {@linkcode ErrorCode}: that object is the scan target of the documentation site's error catalog, which requires every member to carry a phase/severity family rule. `RENDER_ERROR` is the pre-dialect value `RenderError` has always defaulted to — kept verbatim so callers that observe it keep working, and kept out of the catalogue because it is not a failure this package classifies, only a constructor default a caller may override.
"RENDER_ERROR"Keyed-list identity failures. Shared by the server serializer and the client runtime (see `internal/compiled/each-key.ts`), so both executors reject the same data with the same code.
{ readonly ITEM_NOT_A_RECORD: "OE_EACH_ITEM_NOT_A_RECORD"; readonly KEY_NOT_ROUND_TRIPPABLE: "OE_EACH_KEY_NOT_ROUND_TRIPPABLE"; readonly DUPLICATE_KEY: "OE_EACH_KEY_DUPLICATE"; }Error message prefix for all openElement errors.
"[openElement]"Well-known error code constants for reference. String values are always accepted.
{ readonly SSR_RENDER_ERROR: "SSR_RENDER_ERROR"; readonly BOUNDARY_CAUGHT: "BOUNDARY_CAUGHT"; readonly UNKNOWN: "UNKNOWN"; }The pipeline phase an error was raised in.
ErrorPhaseHow severe a framework error is.
ErrorSeverityCallback receiving every reported {@linkcode OpenElementError} for telemetry.
ErrorTelemetryHookSSR/bootstrap failures raised by the public entries (phase `ssr` / `csr`).
{ readonly PROGRAM_MISSING: "OE_PROGRAM_MISSING"; readonly COMPOSITION_DEPTH: "OE_SSR_COMPOSITION_DEPTH"; readonly COMPUTED_FACTORY_MISSING: "OE_COMPUTED_FACTORY_MISSING"; readonly COMPUTED_READONLY: "OE_COMPUTED_READON…One framework failure: {@linkcode OpenElementError} with the caller's code and the phase/severity/recoverability that phase implies. Every throw site in this package goes through this factory (or the `*ErrorCode` tables above) so a code, a phase and a recoverability answer cannot drift per site.
(code: string, message: string, options?: Omit<OpenElementErrorOptions, "code">): OpenElementErrorElement-lifecycle failures: the kernel was driven outside its contract (phase `csr`).
{ readonly DISPOSED: "OE_KERNEL_DISPOSED"; readonly TAG_MISMATCH: "OE_KERNEL_TAG_MISMATCH"; readonly CLAIM_EXECUTOR_MISSING: "OE_KERNEL_CLAIM_EXECUTOR_MISSING"; readonly ROOT_NOT_OWNED: "OE_KERNEL_ROOT_NOT_OWNED"; reado…Framework error carrying a stable code, severity, phase and recoverability contract.
class OpenElementError extends ErrorConstructor options for {@linkcode OpenElementError}; every field is defaulted.
OpenElementErrorOptionsProgram-shape failures: a Part Program (or one of its records) is malformed, or carries a value the wire format cannot express. Phase `validation`: these reject data before any DOM work starts.
{ readonly INVALID_PROGRAM: "OE_PROGRAM_INVALID"; readonly NOT_SERIALIZABLE: "OE_PROGRAM_NOT_SERIALIZABLE"; readonly INVALID_SLOT: "OE_PROGRAM_INVALID_SLOT"; readonly INVALID_SOURCE_SEGMENT: "OE_PROGRAM_INVALID_SOURCE_S…Raise one framework failure and never return: the throwing companion of {@linkcode frameworkError}. The per-module `fail(code, message)` micro-factories bind their failure surface's fixed {@linkcode ErrorPhase} here — one implementation, the phase as a parameter — so a code and a phase cannot drift apart per throw site.
(phase: ErrorPhase, code: string, message: string): neverWhether the authored error prose is kept: `true` everywhere except a production client build, the one context that defines `OE_RUNTIME_MESSAGES` to `false`. Stripping is a payload decision, so it belongs to the browser bundle only — server-side failures keep their prose.
booleanRuntime execution failures raised while a compiled program is serialized, built into fresh DOM, or re-read on a signal write (phase `render`).
{ readonly LIST_VALUE_NOT_ARRAY: "OE_RUNTIME_LIST_VALUE_NOT_ARRAY"; readonly HOST_SIGNAL_MISSING: "OE_RUNTIME_HOST_SIGNAL_MISSING"; readonly HOST_HANDLER_MISSING: "OE_RUNTIME_HOST_HANDLER_MISSING"; readonly HOST_REF_MIS…Compiled server/claim validation failures. The value shipped in 1.0.0-alpha.3 and is kept verbatim; `CompiledProgramValidationError` is its only raiser.
{ readonly PROGRAM_INVALID: "OPEN_ELEMENT_COMPILED_PROGRAM_INVALID"; readonly SINK_REFUSED: "OE_SERVER_SINK_REFUSED"; }Compiled-style application failures (phase `csr`).
{ readonly ADOPTED_STYLES_UNSUPPORTED: "OE_STYLES_ADOPTED_STYLES_UNSUPPORTED"; readonly SHEET_LOAD_FAILED: "OE_STYLES_SHEET_LOAD_FAILED"; readonly INVALID_STYLE_HREF: "OE_STYLES_INVALID_HREF"; readonly SHEET_RULES_UNREA…The one camelCase → kebab-case casing rule for custom-element attribute names, so `<x-el itemCount={5}>` round-trips as `item-count` on every boundary that derives an attribute name from a prop name: the compiler's property metadata, the SSR serializer, and the client attribute handling.
(str: string): stringForbidden sink names — the ONE canonical deny list for every Part Program boundary: the compiler semantic core, the protocol validator (internal/protocol/part-program.ts), and the compiled server/claim validator (internal/compiled/server/shared.ts). This module is import-free and host-free by design (same base-of-graph contract as void-tags.ts): all consumers import it, so a new forbidden sink cannot be enforced on one boundary and missed on another. This module owns the named-sink deny lists and the attribute-name policy built on them (the one shared safe-attribute-name predicate and the one camelCase→kebab-case casing rule); consumers delegate so the boundary cannot diverge. The lists are fail closed and case-insensitive (attribute and property names are compared lowercase, matching the HTML parser's name folding): - `FORBIDDEN_ATTRIBUTE_NAMES`: attribute names that must never be a static attribute or an `attr`/`bool` sink. `srcdoc` smuggles a full HTML document past attribute escaping; `innerHTML` is admissible only through the dedicated trusted-HTML `html` Part, never as a plain attribute name. - `FORBIDDEN_PROPERTY_NAMES`: `prop` sink names that would re-prototype or re-construct the target element (prototype-pollution primitives). - `RAW_TEXT_TAGS`: raw-text elements are outside the compiled grammar — their content cannot be escaped by the serializer.
ReadonlySet<string>Property names the compiler refuses as
ReadonlySet<string>Sink categories the canonical deny list classifies.
ForbiddenSinkKindReturn a human-readable reason when `name` is a forbidden sink of `kind`, or null when the name is admissible. Unknown kinds fail closed with a reason instead of being waved through.
(kind: ForbiddenSinkKind, name: string): string | nullThe one safe-attribute-name predicate (#1033, #602). Attribute *names* are not escaped on any render path, so a name must be valid HTML attribute-name grammar (blocks quote/space injection), must not be an event handler (`on*`, case-insensitive), and must not be a forbidden sink (`innerhtml`/ `srcdoc` — case-insensitive). Every boundary that admits an attribute name — the compiler semantic core, the Part Program validator, the compiled server validator, and the SSR head/meta name checks — delegates here, so the rules cannot diverge per path.
(name: string): booleanElements whose text content must never be interpolated as markup.
ReadonlySet<string>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.
CompatibilityClassificationHow 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.
CompatibilityTierThe 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.
ComponentLayerThe adapter-facing framework options: where routes and islands live, which renderer serializes pages, the default layout and named-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.
FrameworkOptionsRuntime 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.
readonly ["load", "idle", "visible", "only", "none"]Island hydration trigger: 'load' | 'idle' | 'visible' | 'only'.
"load" | "idle" | "visible" | "only" | "none"Layout declaration: `false` disables the layout entirely, `'default'` uses the built-in layout, 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 layout properties the router injects per route.
LayoutConfigLocale-aware resolved path contract.
LocalePathFetch 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.
MiddlewareBlog options stored in the build context by
OpenElementBlogOptionsMinimal build context interface that sub-plugins can use.
OpenElementBuildContextLikei18n options stored in the build context by
OpenElementI18nContextOptionsOne 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.
RouteEntryBranded type: a string that has been HTML-escaped (safe for text content)
SafeHtmlSpecial file kinds the route scanner recognizes by filename: `renderer` and `middleware`.
SpecialFileTypeWhere an island's resolved hydration strategy came from.
StrategySourceBranded type: a string that is intentionally raw/untrusted HTML
UnsafeHtmlPer-island delivery options (hydration strategy, SSR/DSD participation).
IslandOptionsOptions for the build-time island source transform.
IslandTransformOptionsThe island transform output: rewritten source plus extracted facts.
IslandTransformResultThe static-sidecar descriptor router injects into the element compiler.
StaticSidecarDescriptorThe compatibility classification report for one custom element manifest.
CemCompatibilityReportThe 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.
CompatibilityClassificationHow 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.
CompatibilityTierOne documented attribute of a custom element declaration.
OpenElementAttributeOne documented CSS part of a custom element declaration.
OpenElementCssPartOne custom element declaration in a package manifest: tag, members and delivery metadata.
OpenElementDeclarationOne documented custom event of a custom element declaration.
OpenElementEventThe openElement-specific extension block of a package manifest declaration.
OpenElementExtensionsPackage manifest of component declarations (not a Custom Elements Manifest).
OpenElementPackageManifestOne documented slot of a custom element declaration.
OpenElementSlotA declaration's utility-compilation requirement and the package-owned style sources that requirement compiles (the declared-compilation contract; see the router's `style-plan` module for the resolution rules). `required` is the mandatory-compilation dependency: the component's presentation cannot be delivered without the compile, so an application that disables the entry (`tailwind: false`) fails the build with a coded diagnostic instead of shipping an unstyled component. Merely offering a theme source is NOT a requirement — leave `required` unset for a source a consumer may adopt on its own. `sources` are package-relative paths (e.g. `./theme.css`) resolved against THIS package, so a consumer never repeats the owner's declaration. They must exist in the installed package (i.e. ship in the tarball). `dialect` names the CLASS LANGUAGE this component's utility tokens are written in, not the engine that compiles them: the declaration stays provider-neutral, and a selected provider that does not implement the dialect fails the build before any compile. Omitted means `tailwind4` — the language every declaration written before this field existed uses.
OpenElementTailwindDeclarationOne 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).
ModuleVocabularyDescriptorOne static-sidecar descriptor the host injects into the element compiler: the admission granted is a colocated static policy statement (#1473 item 3, the static-sidecar admission pattern).
StaticSidecarDescriptorThe module vocabulary router injects into `analyzeModuleSemantics`.
readonly ModuleVocabularyDescriptor[]One property entry of the compiled custom-elements-manifest metadata.
CemPropertyMetadataVersion of the compiled-module ABI: the statics a generated module carries (`__partProgram`, `__compiledProperties`, `__elementMetadata`, `__observedAttributes`, `__computedFields`) and the runtime facade binds. Bump when the generated-module contract changes shape; generated artifacts stamp both this and PART_PROGRAM_VERSION so consumers can tell format drift from release drift. v2: platform lifecycle callback bodies are emitted inside a boundary-capture wrapper calling the base class's `_captureError` — a generated module now requires a runtime facade carrying that protected method (the v1 shape emitted the bodies verbatim).
2The compiled custom-elements-manifest metadata block of one component.
CompiledCemMetadataThe compiled element metadata the program carries for tooling consumers.
CompiledElementMetadataOne compiled
CompiledPropertyMetadataOperator/literal compatibility for when-Block tests (issue #1372). Both wire validators (this module and the server serializer's shared validator) close the space through this one predicate: - ordering operators require a finite numeric literal; - `equals`/`not-equals` admit a finite number, string, or boolean; - `truthy` admits exactly `true` or `false` (the recorded expectation).
(op: unknown, value: unknown): booleanThe comparison operators a program condition supports.
ConditionOperatorInternal SSR provenance marker on light-mode host tags (#1148). Present only when the host's light subtree was server-rendered under the in-place activation contract: the client binds the existing DOM instead of clearing it, and a parent's activation walk prunes the nested host's subtree. Client rendering never writes it and it is never removed. The writer (internal/compiled/server) and readers (internal/compiled/runtime) import this constant; nothing writes the literal.
"data-oe-light"The wire-validator face of the one canonical attribute-name predicate (delegates to `./forbidden-sinks.ts`); exported for parity tests.
(value: unknown): value is stringAn event binding scoped to each item of an `each` block. The runtime attaches this listener to every item root node created by the block, making per-item handlers (onClick={this.select(row.id)}) expressible without fixed-path event parts.
ItemEventBindingThe Part Program IR version this package defines (currently v2).
2The comment marker closing a part anchor in serialized program markup.
(index: number): stringAnchor marker payloads shared by seed runtime consumers.
(index: number): stringThe serializable Part Program v2: one compiled component as data.
PartProgramV2The one deterministic program consumed by all execution modes.
PartProgramV2String attribute sink bound to a Signal.
ProgramAttrPartOne block the program tracks: the boundaries of a dynamic subtree.
ProgramBlockRecordBoolean attribute sink bound to a Signal.
ProgramBoolPartSpecialized fixed sinks make ownership explicit for class and style text.
ProgramClassPartOne condition clause of a when part.
ProgramConditionOne module dependency the compiled module graph records.
ProgramDependencyRecordA list part: repeats its template node per item of a bound signal.
ProgramEachPartA static element node of the program tree.
ProgramElementNodeThe action one event part dispatches.
ProgramEventActionAn event binding part: listener wiring between DOM event and action.
ProgramEventPartTrusted-HTML content sink (alpha.9). The signal value must carry the runtime TrustedHtml capability; its HTML replaces the target element's content. The target's subtree is opaque to the claim path. The compiler emits this only for an explicit `innerHTML={this.<field>}` sink on an otherwise childless element — there is no implicit or discovery path to raw HTML.
ProgramHtmlPartItem-value text slot; valid only inside an `each` item template. `field` names the item field rendered by this slot — multi-field item templates carry one slot per field, and the compiler always emits it.
ProgramItemValueNodeExact compiler-owned location for one dynamic sink or range anchor.
ProgramLocationA location record also makes the identity auditable without inspecting parts.
ProgramLocationRecordThe discriminated union of dynamic parts a program instantiates.
ProgramPartThe anchor node marking where a part binds in the tree.
ProgramPartAnchorNodeWhere a part sits relative to its anchor.
ProgramPositionDOM property sink bound to a Signal; `path` is retained for seed consumers.
ProgramPropPartA named ref slot is serializable; the generated class supplies the ref value.
ProgramRefPartThe root of one program tree: element, part anchor, or text.
ProgramRootThe kind of source record a program source map entry carries.
ProgramSourceKindThe program source map: authored spans projected onto emitted records.
ProgramSourceMapA half-open [start, end) range into the authored source text.
ProgramSourceRangeOne source-map record: the authored origin of one emitted node or part.
ProgramSourceRecordA style binding part.
ProgramStylePartA static text node of the program tree.
ProgramTextNodeA text interpolation part bound to one signal.
ProgramTextPartThe discriminated union of static tree nodes.
ProgramTreeNodeA conditional part: swaps template branches on a condition.
ProgramWhenPartThe serialized value-type tag of a compiled property default.
PropertyValueTypeHow the compiled component attaches its root: light DOM or a shadow root.
RootModeThe JSON-serializable value shape a compiled property default admits.
SerializableValueThe one `<style>` element the server serializer emits as the first DSD template child when the class carries static styles (renderToString parity — pages never upgrade, so their styles must ship in the payload). The claim path skips exactly this marked node; a marked node on a style-less class is claim drift and fails closed.
"data-oe-static-styles"Validate an unknown value as a Part Program v2. The validator is intentionally strict: unknown instruction kinds, missing ownership records and unsafe paths fail before a runtime can guess at their meaning.
(raw: unknown): asserts raw is PartProgramHTML void elements — the ONE canonical tag set for every serializer, validator, and compiler in the workspace (issue #1220, M4). This module is import-free and host-free by design: it sits at the base of the module graph so the DOM runtime (internal/core/html-escape.ts), the Part Program exchange artifact (internal/protocol/part-program.ts), and the compiler semantic core can all consume the same definition without an import cycle or a second source of truth. Content is the full HTML Standard void-element list, `param` included. Do not redefine this set anywhere else; internal/core/html-escape.ts and internal/protocol/part-program.ts re-export it, and __tests__/void-tags-convergence.test.ts enforces the single owner.
ReadonlySet<string>Idle-hydration scheduling fallback (milliseconds) when neither `requestIdleCallback` nor `requestAnimationFrame` is available.
50Request-body bound (bytes) the generated entry applies to action POST routes; larger uploads belong on API routes with explicit limits.
numberNested element expansion depth bound for `renderToString`: cyclic component composition fails closed instead of recursing without end.
8Deferred 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.
32Part/Block owners one stream route's manifest may address in total across all deferred fields.
64Serialized 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.
numberTyped 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.
64Deferred-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.
30000Property on the stub holding the generated entry's registration-ownership map (tag -> class it registered): a route module that self-registers its tag wins over the entry's registration, and on dev re-evaluation a fresh self-registered class must still win (#952).
"__openEntryDefined"Property on the SSR registry holding the TRUE original `define` method, captured before the generated entry installs its idempotent wrapper. The registry outlives vite dev SSR module re-evaluations, so without this the second evaluation would capture the already-wrapped `define` as its "original" and every forced re-registration would silently early-return through the previous wrapper (#1339 lit dev feedback).
"__openElementOrigDefine"Marker property set to `true` on the SSR customElements stub. Readers must treat the marked registry as re-definable.
"__openElementSsrStub"The hydration delivery hint a component or route carries.
HydrationHintOne render failure record the SSR pipeline reports.
RenderErrorThe 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.
SsrAdmissionDecisionThe host-neutral request handler every runtime adapter and generated server entry exposes: a WinterCG `(request, context?) => Response` with no server engine dialect baked in.
OpenElementRequestHandler<Env>A host runtime adapter: exposes the fetch handler a server engine dispatches to.
RuntimeAdapter<Env>Options one runtime adapter is constructed with.
RuntimeAdapterOptions<Env>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.
RuntimeContext<Env>Read-only signal protocol used by computed values.
ReadonlySignal<T>Alias for APIs that accept either writable or read-only signals.
Signal<T>Runtime/type brand for signals created by the configured reactive engine.
typeof SIGNAL_BRANDSignal engine protocol used by the framework's built-in adapter. This is a deliberate internal seam, not a public compatibility contract: the framework layer talks to signals only through this narrow interface so its call sites stay implementation-agnostic. The package ships and verifies exactly one engine implementation (`preact-engine`, backed by `@preact/signals-core`). Preact's own API is not Element public API, and arbitrary third-party engines are not promised; any future engine would be added behind this protocol rather than inline (charter decision — see #723).
SignalEngineMinimal signal-like object accepted by renderers and bindings.
SignalLike<T>Unsubscribe function returned by subscriptions and effects.
UnsubscribeWritable signal protocol used by openElement integrations.
WritableSignal<T>One API route declaration in the generated entry descriptor.
ApiRouteDeclResult returned by the OpenElement build pipeline.
BuildArtifactsA single client asset emitted by the build pipeline.
BuildClientAsseti18n configuration for the build pipeline.
BuildI18nOptionsA single island input to the build pipeline.
BuildIslandInputManifest produced by the build pipeline.
BuildManifestArtifactOutput configuration for the build pipeline.
BuildOutputOptionsPackage island configuration for the build pipeline.
BuildPackageIslandOptionsA single generated HTML page artifact.
BuildPageArtifactFramework-agnostic plan consumed by the OpenElement build pipeline.
BuildPlanA single route input to the build pipeline.
BuildRouteInputClient island entry shape passed to entry generator.
ClientIslandEntryThe CORS origin policy an API route declares.
CorsOriginConfigThe content-security-policy directives a route or document declares.
CspConfigThe document-level facts a build bakes into the generated entry.
DocumentConfigThe full build-time description of one generated entry: routes, islands, renderers, middleware, document, and layout plans.
EntryDescriptorOne module import the generated entry emits.
ImportDeclOne island the build admits: tag, module path, and delivery facts.
IslandDeclAdapter-owned browser delivery strategy, including media-query admission.
IslandDeliveryStrategyShared island module identity (CL-3 convergence: one base, three shapes). Every island record names the same module the same way — the tag it registers as, the module path that owns it, and whether that module is a package (CEM-derived named export) rather than a local file (default export) — so a rename of the identity touches one declaration, not three. The delivery-strategy fields intentionally stay per-shape (`strategy` on the client entry vs `hydrate` on the build decls): they are different stages' vocabularies, not one field spelled two ways.
IslandModuleIdentityThe layout module a build resolves: tag, import path, and serialized props.
LayoutDeclThe resolved layouts a build ships: the default layout plus named layouts.
LayoutPlanOne middleware module the generated entry composes.
MiddlewareDeclThe scope one middleware applies to (all routes or a named route set).
MiddlewareScopeDeclOne page route declaration in the generated entry descriptor.
PageRouteDeclOne page renderer module registration.
RendererDeclThe resolved layout for one plan slot: disabled (false) or a full declaration.
ResolvedLayoutA single route metadata entry emitted as `routeInfo` by the generated SSG entry module (see entry-render-ssg.ts).
RouteInfoEntrySpeculation Rules configuration for SSG post-processing
SpeculationRulesOptionsUser-facing SSG build behavior switches (OpenElementOptions['ssg']).
SsgBehaviorOptionsPer-page render diagnostics returned by renderRoute()
SsgPageOutputThe per-build render evidence record the SSG engine emits for audit.
SsgRenderEvidenceOptions passed to the shared SSG render pipeline.
SsgRenderOptionsSummary of an SSG render run, returned by ssgRender().
SsgRenderSummaryThe build-time SSR admission decisions per component tag.
SsrAdmissionPlanThe server bundle facts the SSG engine consumes for stream rendering.
SsrBundleBuild-host-only compiled component reached through a route's local import graph. These components participate in recursive SSR/SSG expansion but are not client islands and therefore add no hydration or browser entry.
StaticComponentDeclBuild-only route projection bound to a specific compiled page program.
StreamRouteManifestTags a deferred frame cannot safely install into an owned Part range: the browser installer rejects any frame whose markup carries one of these.
readonly ["script", "style", "template", "iframe", "object", "embed", "base", "meta", "link"]Schemes that make a URL attribute unsafe in a streamed frame.
RegExpURL-carrying attributes the frame check screens for script-bearing scheme obfuscation; only these attribute names are value-screened.
readonly ["href", "src", "action", "formaction", "xlink:href"]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.
32Whether 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.
(name: string, value: string): booleanThe one key marking a sheet whose bytes are a LIVE resource rather than an immutable one (alpha15 S lane, S-C1.3). The dev server serves an authored sheet from a mutable endpoint that hot-updates: the sheet object is the copy the live resource re-fills through `replace()`, so every root that adopted it re-renders on an edit. A root whose serialized markup declares the same URL therefore still ADOPTS this sheet — the declarative `<link>` stays the first-paint / no-JavaScript delivery, and the adopted object is the one an edit reaches. Without that, a CSS-only edit could only be delivered by re-fetching the link, which is a DOM write this protocol does not perform. Production sheets never carry this key: their URL is content-addressed, so the link and the sheet can never disagree and one delivery is the whole story. Build-time and runtime cannot drift because the dev adapter generator interpolates this exact name.
"__openElementStyleSheetLive"The one key under which a sheet carries its readiness promise: the generated client style adapter records it on the sheet it exports, and the element runtime reads the same key to hand styles to roots that are already connected. Build-time and runtime cannot drift because the adapter generator interpolates this exact name. The promise settles once. Fulfillment means the rules were installed through `replace()`; rejection carries the load or replacement failure and keeps its rejected state — an observer may attach its own catch, it must never convert the promise into a fulfilled one.
"__openElementStyleReady"The one key under which a sheet carries the URL of the external CSS resource that delivers its rules: the generated client style adapter records the emitted asset URL on the sheet it exports, and the element runtime compares it against the declarative `<link rel="stylesheet" data-oe-static-styles>` nodes an SSR/DSD template already carries (alpha15 S lane). A root whose serialized markup already references the sheet's URL keeps that link as the delivery and does NOT adopt a second constructable copy — one stylesheet resource, one delivery, no duplicate application. Build-time and runtime cannot drift because the adapter generator interpolates this exact name.
"__openElementStyleSheetUrl"Minimal stylesheet contract (replaceSync + cssRules) satisfied by native and shim sheets.
StyleSheetLikeCross-environment CSSStyleSheet abstraction. In browsers this delegates to the native CSSStyleSheet API. In SSR runtimes it falls back to a minimal in-memory implementation that exposes the subset used by OpenElement and renderToString().
StyleSheetRuleHTML void elements — the ONE canonical tag set for every serializer, validator, and compiler in the workspace (issue #1220, M4). This module is import-free and host-free by design: it sits at the base of the module graph so the DOM runtime (internal/core/html-escape.ts), the Part Program exchange artifact (internal/protocol/part-program.ts), and the compiler semantic core can all consume the same definition without an import cycle or a second source of truth. Content is the full HTML Standard void-element list, `param` included. Do not redefine this set anywhere else; internal/core/html-escape.ts and internal/protocol/part-program.ts re-export it, and __tests__/void-tags-convergence.test.ts enforces the single owner.
ReadonlySet<string>@openelement/element
430 个导出Set the emitted component stylesheet URLs for this server process. Called by the router's generated SSR/SSG entry (build time and request-time startup) with the base-joined asset addresses Phase 2 emitted.
(urls: readonly string[] | null | undefined): voidRoute action: handles form submissions for a page route.
Action<T, Env, Platform, 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.
"x-openelement-action"Context passed to a route action function (extends loader context).
ActionContext<Env, Platform, 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). Success carries no data envelope. The application-loop contract makes a successful non-GET action answer 303 (PRG) — the framework never answers 200 with a rendered page, or with a success document, for a successful mutation — so the fetch channel answers `{ type: 'redirect' }` naming the PRG target and the authored return value is discarded by design. Success data travels the PRG target instead (query state the loader re-runs with, which the props projector then maps; see the router guide's "Form actions" section). The union previously declared a `{ type: 'success' }` member that no code path ever emitted — removed so the type matches the wire. 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.
ActionResult<Failure>Assert that a tag name is a valid custom element name.
(tagName: string): voidCollect 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.
(host: object): Record<string, unknown>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.
CompatibilityClassificationHow 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.
CompatibilityTierThe 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.
ComponentLayerCreate a derived read-only signal recomputed from its dependencies.
<T>(fn: () => T): ReadonlySignal<T>Consumer-local reactive projection of a protocol context value.
<T>(context: Context<T>, host?: HTMLElement): WritableSignal<T>A typed context token: protocol identity (`key`) plus its default value.
Context<T>Create a typed context token shared between provider and consumer elements.
<T>(key: symbol, defaultValue: T): Context<T>Create the per-render document stylesheet collection.
(): DocumentStyleResourcesCreate a {@link Logger} that prefixes every message with `[tag]`.
(tag: string): LoggerCreate one request-local stream shell from a generated route manifest. The manifest hash is checked against the exact runtime wire program before any shell can be produced.
(options: CreateStreamShellOptions): Promise<StreamShellExecutor>Inputs for a request-scoped stream shell executor.
CreateStreamShellOptionsObject prototype keys that must never be injected from untrusted props.
ReadonlySet<string>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.
(id: string, root?: Document | ShadowRoot): HTMLElement | nullThe same document serialization boundary, with only body wrappers left open.
(options?: DocumentWrapOptions): { prefix: string; suffix: string; }The document-level stylesheet resources ONE server render discovered (alpha15 S lane, S-C1.2). A light-root component's DOM lives in the document, so its sheet cannot ride the component's own subtree the way a shadow template's link does: the document owns it. This object is the one carrier between the two halves of that render — the compiled serializer, which discovers a component's external sheets while serializing the component, and the document serializer, which writes the head. It is created per render and never shared, so one page's stylesheets can never reach another page's head.
DocumentStyleResourcesRun a side effect that re-subscribes whenever its signal dependencies change.
(fn: () => void | Unsubscribe): UnsubscribeCompiler-recognized element decorator; inert no-op at runtime.
(_tag: string, _options?: { root?: "light" | "shadow-open" | "shadow-closed"; delegatesFocus?: boolean; formAssociated?: boolean; }): (target: unknown, context?: unknown) => voidInstall 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 shared queue carries a hard capacity cap (fail closed), detached records are swept when a claim root adopts its share (and under queue pressure), and each activation decision deterministically empties that root's own bucket, so post-hydration traffic and removals never grow retention.
(root?: EventTarget, pendingTags?: readonly string[]): voidError message prefix for all openElement errors.
"[openElement]"Base class for elements that catch descendant render/hydration errors and apply a retry policy.
class ErrorBoundary extends OpenElementCallback receiving every reported {@linkcode OpenElementError} for telemetry.
ErrorTelemetryHookEscape 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.
(value: string): stringEscape the five HTML-significant characters in text content.
(str: string): stringFormat an unknown thrown value as a human-readable string.
(e: unknown): stringThe adapter-facing framework options: where routes and islands live, which renderer serializes pages, the default layout and named-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.
FrameworkOptionsRuntime 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.
readonly ["load", "idle", "visible", "only", "none"]Island hydration trigger: 'load' | 'idle' | 'visible' | 'only'.
"load" | "idle" | "visible" | "only" | "none"Idle-hydration scheduling fallback (milliseconds) when neither `requestIdleCallback` nor `requestAnimationFrame` is available.
50Safely 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
(target: Record<string, unknown>, props: Record<string, unknown>, tagName: string, log?: { warn(message: string): void; debug(message: string): void; }): voidShared 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
(key: string): booleanPer-island delivery options (hydration strategy, SSR/DSD participation).
IslandOptionsShared safe-attribute-name predicate (#1033): the SSR face of the one canonical predicate in `../protocol/forbidden-sinks.ts`. A name must be valid HTML attribute-name grammar (blocks quote/space injection, #602), must not be an event handler (`on*`, case-insensitive), and must not be a forbidden sink (`innerhtml`/`srcdoc`). The compiler, protocol validator, and server serializer enforce the same predicate with their own failure strategies; every path delegates to the single implementation, so the boundary cannot diverge.
(name: string): booleanCheck if a tag name is a valid custom element name per HTML spec.
(tagName: string): booleanLayout declaration: `false` disables the layout entirely, `'default'` uses the built-in layout, 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 layout properties the router injects per route.
LayoutConfigRoute loader: fetches data for a page route.
Loader<T, Env, Platform, Route>Context passed to a request-time ('dynamic') route loader.
LoaderContext<Env, Platform, Route>Locale-aware resolved path contract.
LocalePathlogger.ts - Tagged console logger. Lightweight scoped logger. Returns plain functions so it is tree-shakable and has zero class overhead.
LoggerRequest-body bound (bytes) the generated entry applies to action POST routes; larger uploads belong on API routes with explicit limits.
numberNested element expansion depth bound for `renderToString`: cyclic component composition fails closed instead of recursing without end.
8Fetch 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.
MiddlewareCustom 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.
class OpenElement extends OpenElementConfigurationOne documented attribute of a custom element declaration.
OpenElementAttributeOne documented CSS part of a custom element declaration.
OpenElementCssPartOne custom element declaration in a package manifest: tag, members and delivery metadata.
OpenElementDeclarationFramework error carrying a stable code, severity, phase and recoverability contract.
class OpenElementError extends ErrorOne documented custom event of a custom element declaration.
OpenElementEventPackage manifest of component declarations (not a Custom Elements Manifest).
OpenElementPackageManifestHost-agnostic route and asset contracts shared by app and build drivers.
OpenElementRouteKindOne 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`.
OpenElementRouteNodeOne documented slot of a custom element declaration.
OpenElementSlotMedia type of the RFC 9457 action error channel (#863).
"application/problem+json"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.
ProblemDetailsCompiler-recognized property decorator; inert no-op at runtime.
(_options: { reflect: boolean; attribute?: false | string; type?: unknown; converter?: unknown; }): (target: unknown, context?: unknown) => voidProvide a plain protocol value; the provider Signal remains OE-private.
<T>(host: HTMLElement, context: Context<T>, value: T): UnsubscribeRead-only signal protocol used by computed values.
ReadonlySignal<T>Recoverable render-phase error carrying the failing component path and tag.
class RenderError extends OpenElementErrorServer-render one compiled element through canonical Element composition: returns the serialized DSD `html` string directly.
(input: string | CustomElementConstructor, options?: RenderToStringOptions): stringOptions for one `renderToString()` 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.
RenderToStringOptionsReport an {@linkcode OpenElementError} to the telemetry hook, or console.error when none is installed.
(error: OpenElementError): voidOne 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.
RouteEntryCanonical request-time/SSG server route context.
ServerRouteContext<Env, Platform, 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().
ServerRouteMetadataInstall the process-wide error telemetry hook (replaceable for tests, HMR, multi-app pages).
(hook: ErrorTelemetryHook): voidCreate a writable signal through the selected signal engine.
<T>(initialValue: T): WritableSignal<T>Alias for APIs that accept either writable or read-only signals.
Signal<T>Special file kinds the route scanner recognizes by filename: `renderer` and `middleware`.
SpecialFileTypeThe 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.
SsrAdmissionDecisionTags a deferred frame cannot safely install into an owned Part range: the browser installer rejects any frame whose markup carries one of these.
readonly ["script", "style", "template", "iframe", "object", "embed", "base", "meta", "link"]Schemes that make a URL attribute unsafe in a streamed frame.
RegExpURL-carrying attributes the frame check screens for script-bearing scheme obfuscation; only these attribute names are value-screened.
readonly ["href", "src", "action", "formaction", "xlink:href"]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.
32Deferred 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.
32Part/Block owners one stream route's manifest may address in total across all deferred fields.
64Serialized 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.
numberTyped 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.
64Deferred-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.
30000Initial shell, typed seed, and bounded updates for a stream shell request.
StreamShellExecutorMaps route-local deferred fields to the compiled Part or Block owners they update.
StreamShellManifestCross-realm StyleSheet constructor: the native CSSStyleSheet or the internal shim.
new () => StyleSheetLikeMinimal stylesheet contract (replaceSync + cssRules) satisfied by native and shim sheets.
StyleSheetLikeMark an HTML string as trusted for explicit `innerHTML` sinks (the trust does not serialize).
(html: string): TrustedHtmlOpaque capability marking HTML the application has explicitly vetted as trusted.
TrustedHtmlWhether 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.
(name: string, value: string): booleanWrap 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).
(html: string, options?: DocumentWrapOptions): stringRequest 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.
"x-openelement-action"Assert that a tag name is a valid custom element name.
(tagName: string): voidObject prototype keys that must never be injected from untrusted props.
ReadonlySet<string>Error message prefix for all openElement errors.
"[openElement]"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.
readonly ["load", "idle", "visible", "only", "none"]Island hydration trigger: 'load' | 'idle' | 'visible' | 'only'.
"load" | "idle" | "visible" | "only" | "none"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
(target: Record<string, unknown>, props: Record<string, unknown>, tagName: string, log?: { warn(message: string): void; debug(message: string): void; }): voidShared 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
(key: string): booleanShared safe-attribute-name predicate (#1033): the SSR face of the one canonical predicate in `../protocol/forbidden-sinks.ts`. A name must be valid HTML attribute-name grammar (blocks quote/space injection, #602), must not be an event handler (`on*`, case-insensitive), and must not be a forbidden sink (`innerhtml`/`srcdoc`). The compiler, protocol validator, and server serializer enforce the same predicate with their own failure strategies; every path delegates to the single implementation, so the boundary cannot diverge.
(name: string): booleanCheck if a tag name is a valid custom element name per HTML spec.
(tagName: string): booleanRequest-body bound (bytes) the generated entry applies to action POST routes; larger uploads belong on API routes with explicit limits.
numberFramework error carrying a stable code, severity, phase and recoverability contract.
class OpenElementError extends ErrorMedia type of the RFC 9457 action error channel (#863).
"application/problem+json"Tags a deferred frame cannot safely install into an owned Part range: the browser installer rejects any frame whose markup carries one of these.
readonly ["script", "style", "template", "iframe", "object", "embed", "base", "meta", "link"]Schemes that make a URL attribute unsafe in a streamed frame.
RegExpURL-carrying attributes the frame check screens for script-bearing scheme obfuscation; only these attribute names are value-screened.
readonly ["href", "src", "action", "formaction", "xlink:href"]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.
32Deferred 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.
32Part/Block owners one stream route's manifest may address in total across all deferred fields.
64Serialized 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.
numberTyped 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.
64Deferred-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.
30000Set the emitted component stylesheet URLs for this server process. Called by the router's generated SSR/SSG entry (build time and request-time startup) with the base-joined asset addresses Phase 2 emitted.
(urls: readonly string[] | null | undefined): voidRoute action: handles form submissions for a page route.
Action<T, Env, Platform, 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.
"x-openelement-action"Context passed to a route action function (extends loader context).
ActionContext<Env, Platform, 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). Success carries no data envelope. The application-loop contract makes a successful non-GET action answer 303 (PRG) — the framework never answers 200 with a rendered page, or with a success document, for a successful mutation — so the fetch channel answers `{ type: 'redirect' }` naming the PRG target and the authored return value is discarded by design. Success data travels the PRG target instead (query state the loader re-runs with, which the props projector then maps; see the router guide's "Form actions" section). The union previously declared a `{ type: 'success' }` member that no code path ever emitted — removed so the type matches the wire. 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.
ActionResult<Failure>Assert that a tag name is a valid custom element name.
(tagName: string): voidCollect 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.
(host: object): Record<string, unknown>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.
CompatibilityClassificationHow 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.
CompatibilityTierThe 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.
ComponentLayerCreate a derived read-only signal recomputed from its dependencies.
<T>(fn: () => T): ReadonlySignal<T>Consumer-local reactive projection of a protocol context value.
<T>(context: Context<T>, host?: HTMLElement): WritableSignal<T>A typed context token: protocol identity (`key`) plus its default value.
Context<T>Create a typed context token shared between provider and consumer elements.
<T>(key: symbol, defaultValue: T): Context<T>Create the per-render document stylesheet collection.
(): DocumentStyleResourcesCreate a {@link Logger} that prefixes every message with `[tag]`.
(tag: string): LoggerCreate one request-local stream shell from a generated route manifest. The manifest hash is checked against the exact runtime wire program before any shell can be produced.
(options: CreateStreamShellOptions): Promise<StreamShellExecutor>Inputs for a request-scoped stream shell executor.
CreateStreamShellOptionsObject prototype keys that must never be injected from untrusted props.
ReadonlySet<string>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.
(id: string, root?: Document | ShadowRoot): HTMLElement | nullThe same document serialization boundary, with only body wrappers left open.
(options?: DocumentWrapOptions): { prefix: string; suffix: string; }The document-level stylesheet resources ONE server render discovered (alpha15 S lane, S-C1.2). A light-root component's DOM lives in the document, so its sheet cannot ride the component's own subtree the way a shadow template's link does: the document owns it. This object is the one carrier between the two halves of that render — the compiled serializer, which discovers a component's external sheets while serializing the component, and the document serializer, which writes the head. It is created per render and never shared, so one page's stylesheets can never reach another page's head.
DocumentStyleResourcesRun a side effect that re-subscribes whenever its signal dependencies change.
(fn: () => void | Unsubscribe): UnsubscribeCompiler-recognized element decorator; inert no-op at runtime.
(_tag: string, _options?: { root?: "light" | "shadow-open" | "shadow-closed"; delegatesFocus?: boolean; formAssociated?: boolean; }): (target: unknown, context?: unknown) => voidInstall 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 shared queue carries a hard capacity cap (fail closed), detached records are swept when a claim root adopts its share (and under queue pressure), and each activation decision deterministically empties that root's own bucket, so post-hydration traffic and removals never grow retention.
(root?: EventTarget, pendingTags?: readonly string[]): voidError message prefix for all openElement errors.
"[openElement]"Base class for elements that catch descendant render/hydration errors and apply a retry policy.
class ErrorBoundary extends OpenElementCallback receiving every reported {@linkcode OpenElementError} for telemetry.
ErrorTelemetryHookEscape 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.
(value: string): stringEscape the five HTML-significant characters in text content.
(str: string): stringFormat an unknown thrown value as a human-readable string.
(e: unknown): stringThe adapter-facing framework options: where routes and islands live, which renderer serializes pages, the default layout and named-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.
FrameworkOptionsRuntime 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.
readonly ["load", "idle", "visible", "only", "none"]Island hydration trigger: 'load' | 'idle' | 'visible' | 'only'.
"load" | "idle" | "visible" | "only" | "none"Idle-hydration scheduling fallback (milliseconds) when neither `requestIdleCallback` nor `requestAnimationFrame` is available.
50Safely 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
(target: Record<string, unknown>, props: Record<string, unknown>, tagName: string, log?: { warn(message: string): void; debug(message: string): void; }): voidShared 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
(key: string): booleanPer-island delivery options (hydration strategy, SSR/DSD participation).
IslandOptionsShared safe-attribute-name predicate (#1033): the SSR face of the one canonical predicate in `../protocol/forbidden-sinks.ts`. A name must be valid HTML attribute-name grammar (blocks quote/space injection, #602), must not be an event handler (`on*`, case-insensitive), and must not be a forbidden sink (`innerhtml`/`srcdoc`). The compiler, protocol validator, and server serializer enforce the same predicate with their own failure strategies; every path delegates to the single implementation, so the boundary cannot diverge.
(name: string): booleanCheck if a tag name is a valid custom element name per HTML spec.
(tagName: string): booleanLayout declaration: `false` disables the layout entirely, `'default'` uses the built-in layout, 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 layout properties the router injects per route.
LayoutConfigRoute loader: fetches data for a page route.
Loader<T, Env, Platform, Route>Context passed to a request-time ('dynamic') route loader.
LoaderContext<Env, Platform, Route>Locale-aware resolved path contract.
LocalePathlogger.ts - Tagged console logger. Lightweight scoped logger. Returns plain functions so it is tree-shakable and has zero class overhead.
LoggerRequest-body bound (bytes) the generated entry applies to action POST routes; larger uploads belong on API routes with explicit limits.
numberNested element expansion depth bound for `renderToString`: cyclic component composition fails closed instead of recursing without end.
8Fetch 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.
MiddlewareCustom 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.
class OpenElement extends OpenElementConfigurationOne documented attribute of a custom element declaration.
OpenElementAttributeOne documented CSS part of a custom element declaration.
OpenElementCssPartOne custom element declaration in a package manifest: tag, members and delivery metadata.
OpenElementDeclarationFramework error carrying a stable code, severity, phase and recoverability contract.
class OpenElementError extends ErrorOne documented custom event of a custom element declaration.
OpenElementEventPackage manifest of component declarations (not a Custom Elements Manifest).
OpenElementPackageManifestHost-agnostic route and asset contracts shared by app and build drivers.
OpenElementRouteKindOne 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`.
OpenElementRouteNodeOne documented slot of a custom element declaration.
OpenElementSlotMedia type of the RFC 9457 action error channel (#863).
"application/problem+json"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.
ProblemDetailsCompiler-recognized property decorator; inert no-op at runtime.
(_options: { reflect: boolean; attribute?: false | string; type?: unknown; converter?: unknown; }): (target: unknown, context?: unknown) => voidProvide a plain protocol value; the provider Signal remains OE-private.
<T>(host: HTMLElement, context: Context<T>, value: T): UnsubscribeRead-only signal protocol used by computed values.
ReadonlySignal<T>Recoverable render-phase error carrying the failing component path and tag.
class RenderError extends OpenElementErrorServer-render one compiled element through canonical Element composition: returns the serialized DSD `html` string directly.
(input: string | CustomElementConstructor, options?: RenderToStringOptions): stringOptions for one `renderToString()` 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.
RenderToStringOptionsReport an {@linkcode OpenElementError} to the telemetry hook, or console.error when none is installed.
(error: OpenElementError): voidOne 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.
RouteEntryCanonical request-time/SSG server route context.
ServerRouteContext<Env, Platform, 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().
ServerRouteMetadataInstall the process-wide error telemetry hook (replaceable for tests, HMR, multi-app pages).
(hook: ErrorTelemetryHook): voidCreate a writable signal through the selected signal engine.
<T>(initialValue: T): WritableSignal<T>Alias for APIs that accept either writable or read-only signals.
Signal<T>Special file kinds the route scanner recognizes by filename: `renderer` and `middleware`.
SpecialFileTypeThe 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.
SsrAdmissionDecisionTags a deferred frame cannot safely install into an owned Part range: the browser installer rejects any frame whose markup carries one of these.
readonly ["script", "style", "template", "iframe", "object", "embed", "base", "meta", "link"]Schemes that make a URL attribute unsafe in a streamed frame.
RegExpURL-carrying attributes the frame check screens for script-bearing scheme obfuscation; only these attribute names are value-screened.
readonly ["href", "src", "action", "formaction", "xlink:href"]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.
32Deferred 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.
32Part/Block owners one stream route's manifest may address in total across all deferred fields.
64Serialized 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.
numberTyped 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.
64Deferred-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.
30000Initial shell, typed seed, and bounded updates for a stream shell request.
StreamShellExecutorMaps route-local deferred fields to the compiled Part or Block owners they update.
StreamShellManifestCross-realm StyleSheet constructor: the native CSSStyleSheet or the internal shim.
new () => StyleSheetLikeMinimal stylesheet contract (replaceSync + cssRules) satisfied by native and shim sheets.
StyleSheetLikeMark an HTML string as trusted for explicit `innerHTML` sinks (the trust does not serialize).
(html: string): TrustedHtmlOpaque capability marking HTML the application has explicitly vetted as trusted.
TrustedHtmlWhether 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.
(name: string, value: string): booleanWrap 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).
(html: string, options?: DocumentWrapOptions): stringCompose 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.
<Args extends unknown[]>(middleware: Middleware[], handler: (request: Request, ...args: Args) => Promise<Response>): (request: Request, ...args: Args) => Promise<Response>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.
<Env extends Record<string, unknown> = Record<string, unknown>>(options: RuntimeAdapterOptions<Env>): RuntimeAdapter<Env>Serialize a value to pretty-printed JSON ending with a newline.
(value: unknown): stringInsert markup before a tolerant HTML body close (`</body >`, case-insensitive).
(html: string, content: string): stringNormalize path separators and collapse duplicates. - Backslashes and forward slashes are replaced with the chosen separator. - Repeated separators are collapsed to a single separator.
(path: string, sep?: "/" | "-"): stringThe host-neutral request handler every runtime adapter and generated server entry exposes: a WinterCG `(request, context?) => Response` with no server engine dialect baked in.
OpenElementRequestHandler<Env>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.
(filePath: string): stringruntime.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.
RuntimeContext<Env>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`.
class SsrRenderError extends OpenElementErrorInject 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.
(source: string, options: IslandTransformOptions): IslandTransformResultSet the emitted component stylesheet URLs for this server process. Called by the router's generated SSR/SSG entry (build time and request-time startup) with the base-joined asset addresses Phase 2 emitted.
(urls: readonly string[] | null | undefined): voidRoute action: handles form submissions for a page route.
Action<T, Env, Platform, 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.
"x-openelement-action"Context passed to a route action function (extends loader context).
ActionContext<Env, Platform, 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). Success carries no data envelope. The application-loop contract makes a successful non-GET action answer 303 (PRG) — the framework never answers 200 with a rendered page, or with a success document, for a successful mutation — so the fetch channel answers `{ type: 'redirect' }` naming the PRG target and the authored return value is discarded by design. Success data travels the PRG target instead (query state the loader re-runs with, which the props projector then maps; see the router guide's "Form actions" section). The union previously declared a `{ type: 'success' }` member that no code path ever emitted — removed so the type matches the wire. 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.
ActionResult<Failure>Assert that a tag name is a valid custom element name.
(tagName: string): voidCollect 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.
(host: object): Record<string, unknown>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.
CompatibilityClassificationHow 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.
CompatibilityTierThe 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.
ComponentLayerCreate a derived read-only signal recomputed from its dependencies.
<T>(fn: () => T): ReadonlySignal<T>Consumer-local reactive projection of a protocol context value.
<T>(context: Context<T>, host?: HTMLElement): WritableSignal<T>A typed context token: protocol identity (`key`) plus its default value.
Context<T>Create a typed context token shared between provider and consumer elements.
<T>(key: symbol, defaultValue: T): Context<T>Create the per-render document stylesheet collection.
(): DocumentStyleResourcesCreate a {@link Logger} that prefixes every message with `[tag]`.
(tag: string): LoggerCreate one request-local stream shell from a generated route manifest. The manifest hash is checked against the exact runtime wire program before any shell can be produced.
(options: CreateStreamShellOptions): Promise<StreamShellExecutor>Inputs for a request-scoped stream shell executor.
CreateStreamShellOptionsObject prototype keys that must never be injected from untrusted props.
ReadonlySet<string>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.
(id: string, root?: Document | ShadowRoot): HTMLElement | nullThe same document serialization boundary, with only body wrappers left open.
(options?: DocumentWrapOptions): { prefix: string; suffix: string; }The document-level stylesheet resources ONE server render discovered (alpha15 S lane, S-C1.2). A light-root component's DOM lives in the document, so its sheet cannot ride the component's own subtree the way a shadow template's link does: the document owns it. This object is the one carrier between the two halves of that render — the compiled serializer, which discovers a component's external sheets while serializing the component, and the document serializer, which writes the head. It is created per render and never shared, so one page's stylesheets can never reach another page's head.
DocumentStyleResourcesRun a side effect that re-subscribes whenever its signal dependencies change.
(fn: () => void | Unsubscribe): UnsubscribeCompiler-recognized element decorator; inert no-op at runtime.
(_tag: string, _options?: { root?: "light" | "shadow-open" | "shadow-closed"; delegatesFocus?: boolean; formAssociated?: boolean; }): (target: unknown, context?: unknown) => voidInstall 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 shared queue carries a hard capacity cap (fail closed), detached records are swept when a claim root adopts its share (and under queue pressure), and each activation decision deterministically empties that root's own bucket, so post-hydration traffic and removals never grow retention.
(root?: EventTarget, pendingTags?: readonly string[]): voidError message prefix for all openElement errors.
"[openElement]"Base class for elements that catch descendant render/hydration errors and apply a retry policy.
class ErrorBoundary extends OpenElementCallback receiving every reported {@linkcode OpenElementError} for telemetry.
ErrorTelemetryHookEscape 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.
(value: string): stringEscape the five HTML-significant characters in text content.
(str: string): stringFormat an unknown thrown value as a human-readable string.
(e: unknown): stringThe adapter-facing framework options: where routes and islands live, which renderer serializes pages, the default layout and named-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.
FrameworkOptionsRuntime 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.
readonly ["load", "idle", "visible", "only", "none"]Island hydration trigger: 'load' | 'idle' | 'visible' | 'only'.
"load" | "idle" | "visible" | "only" | "none"Idle-hydration scheduling fallback (milliseconds) when neither `requestIdleCallback` nor `requestAnimationFrame` is available.
50Safely 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
(target: Record<string, unknown>, props: Record<string, unknown>, tagName: string, log?: { warn(message: string): void; debug(message: string): void; }): voidShared 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
(key: string): booleanPer-island delivery options (hydration strategy, SSR/DSD participation).
IslandOptionsShared safe-attribute-name predicate (#1033): the SSR face of the one canonical predicate in `../protocol/forbidden-sinks.ts`. A name must be valid HTML attribute-name grammar (blocks quote/space injection, #602), must not be an event handler (`on*`, case-insensitive), and must not be a forbidden sink (`innerhtml`/`srcdoc`). The compiler, protocol validator, and server serializer enforce the same predicate with their own failure strategies; every path delegates to the single implementation, so the boundary cannot diverge.
(name: string): booleanCheck if a tag name is a valid custom element name per HTML spec.
(tagName: string): booleanLayout declaration: `false` disables the layout entirely, `'default'` uses the built-in layout, 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 layout properties the router injects per route.
LayoutConfigRoute loader: fetches data for a page route.
Loader<T, Env, Platform, Route>Context passed to a request-time ('dynamic') route loader.
LoaderContext<Env, Platform, Route>Locale-aware resolved path contract.
LocalePathlogger.ts - Tagged console logger. Lightweight scoped logger. Returns plain functions so it is tree-shakable and has zero class overhead.
LoggerRequest-body bound (bytes) the generated entry applies to action POST routes; larger uploads belong on API routes with explicit limits.
numberNested element expansion depth bound for `renderToString`: cyclic component composition fails closed instead of recursing without end.
8Fetch 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.
MiddlewareCustom 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.
class OpenElement extends OpenElementConfigurationOne documented attribute of a custom element declaration.
OpenElementAttributeOne documented CSS part of a custom element declaration.
OpenElementCssPartOne custom element declaration in a package manifest: tag, members and delivery metadata.
OpenElementDeclarationFramework error carrying a stable code, severity, phase and recoverability contract.
class OpenElementError extends ErrorOne documented custom event of a custom element declaration.
OpenElementEventPackage manifest of component declarations (not a Custom Elements Manifest).
OpenElementPackageManifestHost-agnostic route and asset contracts shared by app and build drivers.
OpenElementRouteKindOne 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`.
OpenElementRouteNodeOne documented slot of a custom element declaration.
OpenElementSlotMedia type of the RFC 9457 action error channel (#863).
"application/problem+json"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.
ProblemDetailsCompiler-recognized property decorator; inert no-op at runtime.
(_options: { reflect: boolean; attribute?: false | string; type?: unknown; converter?: unknown; }): (target: unknown, context?: unknown) => voidProvide a plain protocol value; the provider Signal remains OE-private.
<T>(host: HTMLElement, context: Context<T>, value: T): UnsubscribeRead-only signal protocol used by computed values.
ReadonlySignal<T>Recoverable render-phase error carrying the failing component path and tag.
class RenderError extends OpenElementErrorServer-render one compiled element through canonical Element composition: returns the serialized DSD `html` string directly.
(input: string | CustomElementConstructor, options?: RenderToStringOptions): stringOptions for one `renderToString()` 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.
RenderToStringOptionsReport an {@linkcode OpenElementError} to the telemetry hook, or console.error when none is installed.
(error: OpenElementError): voidOne 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.
RouteEntryCanonical request-time/SSG server route context.
ServerRouteContext<Env, Platform, 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().
ServerRouteMetadataInstall the process-wide error telemetry hook (replaceable for tests, HMR, multi-app pages).
(hook: ErrorTelemetryHook): voidCreate a writable signal through the selected signal engine.
<T>(initialValue: T): WritableSignal<T>Alias for APIs that accept either writable or read-only signals.
Signal<T>Special file kinds the route scanner recognizes by filename: `renderer` and `middleware`.
SpecialFileTypeThe 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.
SsrAdmissionDecisionTags a deferred frame cannot safely install into an owned Part range: the browser installer rejects any frame whose markup carries one of these.
readonly ["script", "style", "template", "iframe", "object", "embed", "base", "meta", "link"]Schemes that make a URL attribute unsafe in a streamed frame.
RegExpURL-carrying attributes the frame check screens for script-bearing scheme obfuscation; only these attribute names are value-screened.
readonly ["href", "src", "action", "formaction", "xlink:href"]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.
32Deferred 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.
32Part/Block owners one stream route's manifest may address in total across all deferred fields.
64Serialized 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.
numberTyped 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.
64Deferred-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.
30000Initial shell, typed seed, and bounded updates for a stream shell request.
StreamShellExecutorMaps route-local deferred fields to the compiled Part or Block owners they update.
StreamShellManifestCross-realm StyleSheet constructor: the native CSSStyleSheet or the internal shim.
new () => StyleSheetLikeMinimal stylesheet contract (replaceSync + cssRules) satisfied by native and shim sheets.
StyleSheetLikeMark an HTML string as trusted for explicit `innerHTML` sinks (the trust does not serialize).
(html: string): TrustedHtmlOpaque capability marking HTML the application has explicitly vetted as trusted.
TrustedHtmlWhether 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.
(name: string, value: string): booleanWrap 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).
(html: string, options?: DocumentWrapOptions): stringCreate the per-render document stylesheet collection.
(): DocumentStyleResourcesThe document-level stylesheet resources ONE server render discovered (alpha15 S lane, S-C1.2). A light-root component's DOM lives in the document, so its sheet cannot ride the component's own subtree the way a shadow template's link does: the document owns it. This object is the one carrier between the two halves of that render — the compiled serializer, which discovers a component's external sheets while serializing the component, and the document serializer, which writes the head. It is created per render and never shared, so one page's stylesheets can never reach another page's head.
DocumentStyleResourcesEscape 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.
(value: string): stringEscape a string for use as an attribute value (double-quoted)
(value: unknown): stringEscape the five HTML-significant characters in text content.
(str: string): stringTrue when an href has the shape a framework-emitted component stylesheet address takes: a site-absolute path or an absolute http(s) URL, without whitespace or markup-significant characters. ONE rule for both sinks that serialize such an address — the DSD template's links and the document head's — so a component's stylesheet reaches a browser the same way whichever root kind the component has.
(href: string): booleanBranded type: a string that has been HTML-escaped (safe for text content)
SafeHtmlMark an HTML string as trusted for explicit `innerHTML` sinks (the trust does not serialize).
(html: string): TrustedHtmlOpaque capability marking HTML the application has explicitly vetted as trusted.
TrustedHtmlBranded type: a string that is intentionally raw/untrusted HTML
UnsafeHtmlWrap 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).
(html: string, options?: DocumentWrapOptions): stringTypechecking-only fragment marker; fails closed when executed at runtime.
(_props?: unknown): JSX.ElementJSX type interface consumed by TypeScript's automatic JSX transform.
anyTypechecking-only factory; fails closed when executed at runtime.
(_type: unknown, _props: unknown, _key: unknown, _isStaticChildren: unknown, _source: unknown, _self: unknown): JSX.ElementTypechecking-only fragment marker; fails closed when executed at runtime.
(_props?: unknown): JSX.ElementTypechecking-only factory; fails closed when executed at runtime.
(_type: unknown, _props: unknown): JSX.ElementJSX type interface consumed by TypeScript's automatic JSX transform.
anyTypechecking-only factory; fails closed when executed at runtime.
(_type: unknown, _props: unknown): JSX.ElementCreate a {@link Logger} that prefixes every message with `[tag]`.
(tag: string): LoggerCreate a fresh, empty warning scope for one render.
(): WarnScopelogger.ts - Tagged console logger. Lightweight scoped logger. Returns plain functions so it is tree-shakable and has zero class overhead.
LoggerWarn at most once per `key` for the given render {@link WarnScope}, falling back to a process-wide set when no scope is passed.
(key: string, logger: Logger, msg: string, scope?: WarnScope): voidA render-scoped warning tracker. Pass a fresh `WarnScope` (via `createWarnScope()`) into `warnOnce` at a render entry (e.g. once per SSR document in `wrapInDocument`). Suppression is therefore scoped to a single render: the next page/request gets a new scope and the same key can warn again, so one muted key can never silence a diagnostic across all requests/SSG pages (#643).
WarnScopeSet the emitted component stylesheet URLs for this server process. Called by the router's generated SSR/SSG entry (build time and request-time startup) with the base-joined asset addresses Phase 2 emitted.
(urls: readonly string[] | null | undefined): voidRoute action: handles form submissions for a page route.
Action<T, Env, Platform, 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.
"x-openelement-action"Context passed to a route action function (extends loader context).
ActionContext<Env, Platform, 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). Success carries no data envelope. The application-loop contract makes a successful non-GET action answer 303 (PRG) — the framework never answers 200 with a rendered page, or with a success document, for a successful mutation — so the fetch channel answers `{ type: 'redirect' }` naming the PRG target and the authored return value is discarded by design. Success data travels the PRG target instead (query state the loader re-runs with, which the props projector then maps; see the router guide's "Form actions" section). The union previously declared a `{ type: 'success' }` member that no code path ever emitted — removed so the type matches the wire. 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.
ActionResult<Failure>Assert that a tag name is a valid custom element name.
(tagName: string): voidCollect 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.
(host: object): Record<string, unknown>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.
CompatibilityClassificationHow 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.
CompatibilityTierThe 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.
ComponentLayerCreate a derived read-only signal recomputed from its dependencies.
<T>(fn: () => T): ReadonlySignal<T>Consumer-local reactive projection of a protocol context value.
<T>(context: Context<T>, host?: HTMLElement): WritableSignal<T>A typed context token: protocol identity (`key`) plus its default value.
Context<T>Create a typed context token shared between provider and consumer elements.
<T>(key: symbol, defaultValue: T): Context<T>Create the per-render document stylesheet collection.
(): DocumentStyleResourcesCreate a {@link Logger} that prefixes every message with `[tag]`.
(tag: string): LoggerCreate one request-local stream shell from a generated route manifest. The manifest hash is checked against the exact runtime wire program before any shell can be produced.
(options: CreateStreamShellOptions): Promise<StreamShellExecutor>Inputs for a request-scoped stream shell executor.
CreateStreamShellOptionsObject prototype keys that must never be injected from untrusted props.
ReadonlySet<string>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.
(id: string, root?: Document | ShadowRoot): HTMLElement | nullThe same document serialization boundary, with only body wrappers left open.
(options?: DocumentWrapOptions): { prefix: string; suffix: string; }The document-level stylesheet resources ONE server render discovered (alpha15 S lane, S-C1.2). A light-root component's DOM lives in the document, so its sheet cannot ride the component's own subtree the way a shadow template's link does: the document owns it. This object is the one carrier between the two halves of that render — the compiled serializer, which discovers a component's external sheets while serializing the component, and the document serializer, which writes the head. It is created per render and never shared, so one page's stylesheets can never reach another page's head.
DocumentStyleResourcesRun a side effect that re-subscribes whenever its signal dependencies change.
(fn: () => void | Unsubscribe): UnsubscribeCompiler-recognized element decorator; inert no-op at runtime.
(_tag: string, _options?: { root?: "light" | "shadow-open" | "shadow-closed"; delegatesFocus?: boolean; formAssociated?: boolean; }): (target: unknown, context?: unknown) => voidInstall 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 shared queue carries a hard capacity cap (fail closed), detached records are swept when a claim root adopts its share (and under queue pressure), and each activation decision deterministically empties that root's own bucket, so post-hydration traffic and removals never grow retention.
(root?: EventTarget, pendingTags?: readonly string[]): voidError message prefix for all openElement errors.
"[openElement]"Base class for elements that catch descendant render/hydration errors and apply a retry policy.
class ErrorBoundary extends OpenElementCallback receiving every reported {@linkcode OpenElementError} for telemetry.
ErrorTelemetryHookEscape 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.
(value: string): stringEscape the five HTML-significant characters in text content.
(str: string): stringFormat an unknown thrown value as a human-readable string.
(e: unknown): stringThe adapter-facing framework options: where routes and islands live, which renderer serializes pages, the default layout and named-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.
FrameworkOptionsRuntime 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.
readonly ["load", "idle", "visible", "only", "none"]Island hydration trigger: 'load' | 'idle' | 'visible' | 'only'.
"load" | "idle" | "visible" | "only" | "none"Idle-hydration scheduling fallback (milliseconds) when neither `requestIdleCallback` nor `requestAnimationFrame` is available.
50Safely 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
(target: Record<string, unknown>, props: Record<string, unknown>, tagName: string, log?: { warn(message: string): void; debug(message: string): void; }): voidShared 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
(key: string): booleanPer-island delivery options (hydration strategy, SSR/DSD participation).
IslandOptionsShared safe-attribute-name predicate (#1033): the SSR face of the one canonical predicate in `../protocol/forbidden-sinks.ts`. A name must be valid HTML attribute-name grammar (blocks quote/space injection, #602), must not be an event handler (`on*`, case-insensitive), and must not be a forbidden sink (`innerhtml`/`srcdoc`). The compiler, protocol validator, and server serializer enforce the same predicate with their own failure strategies; every path delegates to the single implementation, so the boundary cannot diverge.
(name: string): booleanCheck if a tag name is a valid custom element name per HTML spec.
(tagName: string): booleanLayout declaration: `false` disables the layout entirely, `'default'` uses the built-in layout, 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 layout properties the router injects per route.
LayoutConfigRoute loader: fetches data for a page route.
Loader<T, Env, Platform, Route>Context passed to a request-time ('dynamic') route loader.
LoaderContext<Env, Platform, Route>Locale-aware resolved path contract.
LocalePathlogger.ts - Tagged console logger. Lightweight scoped logger. Returns plain functions so it is tree-shakable and has zero class overhead.
LoggerRequest-body bound (bytes) the generated entry applies to action POST routes; larger uploads belong on API routes with explicit limits.
numberNested element expansion depth bound for `renderToString`: cyclic component composition fails closed instead of recursing without end.
8Fetch 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.
MiddlewareCustom 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.
class OpenElement extends OpenElementConfigurationOne documented attribute of a custom element declaration.
OpenElementAttributeOne documented CSS part of a custom element declaration.
OpenElementCssPartOne custom element declaration in a package manifest: tag, members and delivery metadata.
OpenElementDeclarationFramework error carrying a stable code, severity, phase and recoverability contract.
class OpenElementError extends ErrorOne documented custom event of a custom element declaration.
OpenElementEventPackage manifest of component declarations (not a Custom Elements Manifest).
OpenElementPackageManifestHost-agnostic route and asset contracts shared by app and build drivers.
OpenElementRouteKindOne 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`.
OpenElementRouteNodeOne documented slot of a custom element declaration.
OpenElementSlotMedia type of the RFC 9457 action error channel (#863).
"application/problem+json"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.
ProblemDetailsCompiler-recognized property decorator; inert no-op at runtime.
(_options: { reflect: boolean; attribute?: false | string; type?: unknown; converter?: unknown; }): (target: unknown, context?: unknown) => voidProvide a plain protocol value; the provider Signal remains OE-private.
<T>(host: HTMLElement, context: Context<T>, value: T): UnsubscribeRead-only signal protocol used by computed values.
ReadonlySignal<T>Recoverable render-phase error carrying the failing component path and tag.
class RenderError extends OpenElementErrorServer-render one compiled element through canonical Element composition: returns the serialized DSD `html` string directly.
(input: string | CustomElementConstructor, options?: RenderToStringOptions): stringOptions for one `renderToString()` 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.
RenderToStringOptionsReport an {@linkcode OpenElementError} to the telemetry hook, or console.error when none is installed.
(error: OpenElementError): voidOne 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.
RouteEntryCanonical request-time/SSG server route context.
ServerRouteContext<Env, Platform, 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().
ServerRouteMetadataInstall the process-wide error telemetry hook (replaceable for tests, HMR, multi-app pages).
(hook: ErrorTelemetryHook): voidCreate a writable signal through the selected signal engine.
<T>(initialValue: T): WritableSignal<T>Alias for APIs that accept either writable or read-only signals.
Signal<T>Special file kinds the route scanner recognizes by filename: `renderer` and `middleware`.
SpecialFileTypeThe 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.
SsrAdmissionDecisionTags a deferred frame cannot safely install into an owned Part range: the browser installer rejects any frame whose markup carries one of these.
readonly ["script", "style", "template", "iframe", "object", "embed", "base", "meta", "link"]Schemes that make a URL attribute unsafe in a streamed frame.
RegExpURL-carrying attributes the frame check screens for script-bearing scheme obfuscation; only these attribute names are value-screened.
readonly ["href", "src", "action", "formaction", "xlink:href"]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.
32Deferred 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.
32Part/Block owners one stream route's manifest may address in total across all deferred fields.
64Serialized 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.
numberTyped 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.
64Deferred-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.
30000Initial shell, typed seed, and bounded updates for a stream shell request.
StreamShellExecutorMaps route-local deferred fields to the compiled Part or Block owners they update.
StreamShellManifestCross-realm StyleSheet constructor: the native CSSStyleSheet or the internal shim.
new () => StyleSheetLikeMinimal stylesheet contract (replaceSync + cssRules) satisfied by native and shim sheets.
StyleSheetLikeMark an HTML string as trusted for explicit `innerHTML` sinks (the trust does not serialize).
(html: string): TrustedHtmlOpaque capability marking HTML the application has explicitly vetted as trusted.
TrustedHtmlWhether 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.
(name: string, value: string): booleanWrap 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).
(html: string, options?: DocumentWrapOptions): stringConstruct one element's HTML. `attrs` values are the wire truth: `true` emits a bare attribute, `false`/`null`/`undefined` omit it, arrays and records coerce for `class`/`style` exactly like the serializer, and every other value is attribute-escaped through `escapeAttr`. The reserved `innerHTML` key is the trusted-HTML sink: its value must carry the trustedHtml brand and becomes the element's content (children must be empty — the compiler's shared walk already enforces that shape). `children` are FINAL HTML strings (static text is escaped at compile time, dynamic text arrives through `__t`, nested components through `__ssr` or a direct compiled call).
(tag: string, attrs?: Record<string, unknown>, children?: readonly unknown[]): stringRender one registered compiled host (an
(tag: string, props?: Record<string, unknown>, sourceInfo?: SsrSourceInfo, composition?: SsrComposition): stringEscape one dynamic text value (the ONLY channel untrusted text may take into a server function component's output). Coercion matches the serializer's text-Part pipeline exactly: displayValue, then the ONE `escapeText`.
(value: unknown): string@openelement/compiler
48 个导出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.
(source: string, fileName: string, options?: ModuleSemanticsOptions): ModuleSemanticFactsOne owner's class-candidate facts: the build (or dev server) that created it is the only writer, its stylesheet emitter the only reader.
ClassCandidateRegistryClear without reading — the hygiene a fresh build invocation starts with.
(): voidDrop every registered edge (a build's bookkeeping is its own lifetime).
(): voidThe admitted class candidates of one compiled artifact module, or undefined when the module does not carry the emitted fact. Tolerates both artifact forms the pack pipeline produces (the compiler's raw TypeScript emission and the packed, type-stripped module) — the parse is ScriptKind.TSX for exactly the reason the style-edge recovery documents.
(source: string, fileName: string): readonly string[] | undefinedThe `.css` style edges of one compiled artifact module, in authored order — or undefined when the module is not a shape this recovery adopts. Never throws and never guesses: a module without the Part Program marker, without a `.css` specifier, without an arrayed `static styles`, or with a sheet import no class arrays is left entirely to the graph's normal channels, exactly as before this recovery existed. Adoption is all-or-nothing per module, so it can never turn a working module into a fail-closed intercept while half its edges stay unregistered. The read tolerates both artifact forms the pack pipeline produces: the compiler's raw emission (TypeScript syntax, e.g. a `type`-annotated styles member) and the packed module (types stripped by the packer). The AST parse is ScriptKind.TSX for exactly that reason — a diagnostics gate on the file extension would refuse the raw form and silently drop its edges.
(source: string, fileName: string): readonly string[] | undefinedError shape consumed by the Vite plugin and compiler tests.
class CompiledElementError extends CompilerDiagnosticErrorThe `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.
(options?: CompiledElementPluginOptions): PluginCompile 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
(code: string, id: string, options?: SemanticCoreOptions): CompileElementResult | nullCompile 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.
(source: string, fileName: string, options?: SemanticCoreOptions): CompileElementResultThe 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.
CompileElementResultProject the compiler's already-structured diagnostics onto the protocol's {@linkcode DiagnosticEnvelope} shape. An empty list projects to an empty list — the caller keeps its own fallback rather than inventing a record.
(diagnostics: ReadonlyArray<ProjectableCompilerDiagnostic>): DiagnosticEnvelope[]The host-build admission bridge: compile `code` through the server function component lane when — and only when — this module belongs to it. - a module carrying a compiled-element decorator (or an unsupported decorator spelling, which the class lane compiles so it fails closed with OEC9027) belongs to the class lane: null; - a module with no discovered server function component has nothing to admit: null; - a non-`.tsx` id can never carry the JSX grammar: null; - the cheap `export` + `<` prefilter (the same conservative superset idea the class lane's prefilter uses) keeps plainly inert modules off the parse. Everything else goes through {@link compileServerComponentModule}, whose diagnostics fail the build closed.
(code: string, id: string, options?: ServerComponentCompileOptions): CompileServerComponentResult | nullCompile one authored TSX module's server function components into the generative constructor module. Returns null for modules with no exported JSX-returning function (nothing to admit). Fails closed with a {@link CompiledElementError} carrying the ordered OEC diagnostics.
(source: string, fileName: string, options?: ServerComponentCompileOptions): CompileServerComponentResult | nullThe compiled server function component module.
CompileServerComponentResultCreate one owner's registry (see the lifetime note above).
(): ClassCandidateRegistryProject compiler diagnostics onto the adapter's error shape. Returns null for an empty diagnostics list: there is nothing to locate or render, and the caller keeps its own fallback rather than inventing a location.
(diagnostics: CompilerDiagnostic[], source: string, id: string): PluginDiagnosticError | nullA source-aware compiler diagnostic: stable OEC code, message and source range.
ElementCompilerDiagnosticOne 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.
EmittedModuleDiagnosticHow the emitted module's imports resolve, and any virtual files to add.
EmittedModuleTypeCheckOptions`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.
(code: string, fileName: string, options?: EmittedModuleTypeCheckOptions): booleanThe edge a resolved sheet module id carries, if any.
(moduleId: string): RegisteredStyleRequest | undefinedPrecise second stage behind the 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.
(code: string, id: string): booleanTrue when the importing module has registered edges (query suffixes ignored).
(importerId: string): booleanCheap first stage only — NOT a recognizer. The match keeps plain modules off the AST path and may false-positive (any '@' — inside a string literal, comment, or import specifier — matches); binding provenance and admission are decided exclusively by the semantic core.
(code: string, id: string): booleanThe light-root scope tag of a compiled Part Program — undefined for a shadow-root program, whose sheets ship exactly as authored (they already have a boundary). One reader for the fact, shared by both host bindings of the compiled-element transform (the build plugin and the dev/HMR plugin) and by the compiled-artifact read.
(program: unknown): string | undefinedThe 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.
ModuleSemanticFactsHost-supplied vocabulary extensions for the module scan.
ModuleSemanticsOptionsOne 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).
ModuleVocabularyDescriptorRollup-compatible error shape emitted by the Vite adapter boundary.
PluginDiagnosticErrorThe same recovery, read once for both facts an artifact states: its edges and its root scope (alpha15 S lane, S-C1.2). The scope comes from the module's own Part Program literal — the emitter writes it verbatim, so the packed form needs no second source of truth and no assumption about which root kind a shipped package used.
(source: string, fileName: string): CompiledArtifactStyleRead | undefinedRecord one compile failure's envelopes for the build exit (#1612).
(diagnostics: ReadonlyArray<ProjectableCompilerDiagnostic>): voidOne registered style edge: the authored import's build-graph coordinates.
RegisteredStyleRequestRegister one module's style edges (the registry's one write path, S-C1.4). The importing component's root scope is part of every edge it registers (alpha15 S lane, S-C1.2): a light-root component's sheets leave the build wrapped in `@scope (<tag>)`, so the tag travels to the intercept through the registry key. A shipped artifact states the same fact in its Part Program literal. The Vite transform is the caller for a module the bundler processes; a build host that admits a module for its ADMISSION FACTS alone (a Page or Layout the server renders and no island imports) calls the same step with the same compiled program — no second writer, no second registry.
(id: string, specifiers: readonly string[], scopeTag: string | undefined): voidRegister one generated edge (idempotent per module id — recompiles overwrite).
(request: RegisteredStyleRequest): voidHost-supplied admission extensions for the semantic core.
SemanticCoreOptionsHost-supplied inputs for the server function component compile.
ServerComponentCompileOptionsCompile-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, 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.
(file: string, root: string | undefined, workspaceRoot?: string): stringOne static-sidecar descriptor the host injects into the element compiler: the admission granted is a colocated static policy statement (#1473 item 3, the static-sidecar admission pattern).
StaticSidecarDescriptorStrip 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).
(code: string): stringEvery edge whose sheet file is the given path — the dev HMR reverse lookup.
(file: string): RegisteredStyleRequest[]The sheet file's absolute path for one authored edge: the importing module's directory joined with the authored specifier. Relative specifiers only (the compiler refuses bare ones), so the join is total. Parent segments (`../theme.css`) resolve lexically against the directory — the key must be the path the bundler's resolver lands on, never a verbatim `..` id no lookup can match.
(importerId: string, specifier: string): stringThe registry key for one authored edge: the sheet file's resolved path, plus the importing component's light-root scope tag when it has one. Query suffixes on the importer id (dev-time cache busting) are stripped, so recompiles re-register under one key; the full relative path keeps same-named sheets in sibling subdirectories distinct edges. The scope tag rides the key because the emitted asset is a different resource per scope: a light root's sheet is served wrapped in `@scope (<tag>)`. Registering an edge passes the tag explicitly (the caller is the compile that just proved it); the intercept resolves a `.css` import from `(importer, specifier)` alone, so it reads the same fact back through the importer index. Both paths land on one key for one edge, and a disagreement can only fail closed at the intercept — never emit an unscoped asset.
(importerId: string, specifier: string, scopeTag?: string): stringEvery edge one importing module declared. The host build uses it to emit the style resources of modules it admitted for their edges alone (S-C1.4: a Page or Layout the server renders and no island imports).
(importerId: string): RegisteredStyleRequest[]Drain the recorded envelopes: the exit reads them exactly once.
(): DiagnosticEnvelope[]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.
(code: string, fileName: string, options?: EmittedModuleTypeCheckOptions): EmittedModuleDiagnostic[]Validate an unknown value as a Part Program v2. The validator is intentionally strict: unknown instruction kinds, missing ownership records and unsafe paths fail before a runtime can guess at their meaning.
(raw: unknown): asserts raw is PartProgramThe `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.
(options?: CompiledElementPluginOptions): Plugin@openelement/router
215 个导出Route action: handles form submissions for a page route.
Action<T, Env, Platform, 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.
"x-openelement-action"Context passed to a route action function (extends loader context).
ActionContext<Env, Platform, 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.
ActionOutcome<Data>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). Success carries no data envelope. The application-loop contract makes a successful non-GET action answer 303 (PRG) — the framework never answers 200 with a rendered page, or with a success document, for a successful mutation — so the fetch channel answers `{ type: 'redirect' }` naming the PRG target and the authored return value is discarded by design. Success data travels the PRG target instead (query state the loader re-runs with, which the props projector then maps; see the router guide's "Form actions" section). The union previously declared a `{ type: 'success' }` member that no code path ever emitted — removed so the type matches the wire. 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.
ActionResult<Failure>Canonical application-level classification for an action return value. Server and SPA executors project this result differently, but neither may redefine validation failure or admit a raw Response as action data.
<Data>(result: Data): ActionOutcome<Data>Default convention base: the directory the tokens/layout/data conventions resolve under when `dirs` is omitted (or has no shared leading segment).
"app"Default component directory (`app/components`), the `dirs.components` default.
"app/components"Convention path for the structural document-head module (`app/head.tsx`).
"app/head.tsx"Convention-relative suffix of the structural document-head module.
"head.tsx"Default island directory (`app/islands`), the `dirs.islands` default.
"app/islands"Convention path for the auto-registered layout.
"app/layout.tsx"Convention-relative suffix of the auto-registered layout.
"layout.tsx"The tag name the convention layout is registered under.
"app-layout"The site-title convention source (the package.json `name` field).
"package.json"Default route directory (`app/routes`), the `dirs.routes` default.
"app/routes"Convention-relative suffix of the design-token stylesheet.
"styles/tokens.css"Convention path for the design-token stylesheet.
"app/styles/tokens.css"The structural document-head convention path for a resolved `dirs` block.
(base: string): stringThe layout convention path for a resolved `dirs` block.
(base: string): stringThe token stylesheet convention path for a resolved `dirs` block.
(base: string): stringBuild the canonical OpenElement request context from a platform request event.
<Env extends Record<string, unknown> = Record<string, unknown>>(options: CreateRequestContextOptions<Env>): OpenElementRequestContext<Env>Inputs for building an {@linkcode OpenElementRequestContext} from a platform request event.
CreateRequestContextOptions<Env>`defineConfig()` — identity helper that pins the config file's shape.
(config: OpenElementUserConfig): OpenElementUserConfigValidate and register an island delivery descriptor; returns the normalized config.
(config: IslandConfig): IslandConfigAttach 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 ?? '' }), }); The server function page form (alpha15 server lane) passes the module's exported TSX component function instead — the compiler has already lowered it to a generative HTML constructor, so the same call admits it as a `kind: 'function-page'` descriptor whose render IS that function: export function Home(props: { heading: string }) { return <main><h1>{props.heading}</h1></main>; } export const loader = async () => ({ heading: 'Home' }); export default definePage(Home, { head: { title: 'Home' } }); Runtime discriminant (one rule, no text sniffing): a first argument that is an element CLASS — a value carrying `__partProgram` (what the compiled- element transform emits) or class syntax (its `prototype` is a non-writable own property; plain functions and arrows are not classes) — takes the class branch; any other function takes the function-page branch. Non-functions fail closed with NOT_COMPILED_CLASS.
<Data = unknown, Params extends Record<string, string> = Record<string, string>>(componentClass: CustomElementConstructor, descriptor?: PageDescriptorInput<Data, Params>): PageComponentConstructor<Data, Params>Return a structured action failure with an HTTP status and typed data payload.
<Data>(status: number, data: Data): OpenElementActionFailure<Data>The route-module default export shape a definePage() component call produces.
FunctionPageComponent<Data, Params>Type guard for {@linkcode OpenElementActionFailure}, including its duck-typed cross-realm shape.
(error: unknown): error is OpenElementActionFailurePer-island delivery configuration (SSR/DSD participation and hydration strategy).
IslandConfigAdapter-owned browser delivery strategy, including media-query admission.
IslandDeliveryStrategyType guard for {@linkcode OpenElementNotFound}, including its duck-typed cross-realm shape.
(error: unknown): error is OpenElementNotFoundType guard for {@linkcode OpenElementRedirect}, including its duck-typed cross-realm shape.
(error: unknown): error is OpenElementRedirectA 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.
JsonValueRoute loader: fetches data for a page route.
Loader<T, Env, Platform, Route>Context passed to a request-time ('dynamic') route loader.
LoaderContext<Env, Platform, Route>Throw an {@linkcode OpenElementNotFound} to render the 404 path.
(message?: string): neverAccepted keys inside `build`.
readonly string[]Canonical config-file name, resolved in the project root.
"openelement.config.ts"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.
readonly string[]Accepted keys inside `dirs`.
readonly string[]Accepted keys inside `head`.
readonly string[]Keys of one `head.scripts` entry.
readonly string[]Head keys that carry a plain string value.
readonly string[]Accepted keys inside `i18n`.
readonly string[]Accepted keys inside `layout`.
readonly string[]Accepted keys inside `middleware`.
readonly string[]Accepted keys inside `styles`.
readonly string[]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).
class OpenElementActionFailureBuild-output switches.
OpenElementBuildConfigSource roots; see the `dirs` section of the module doc comment.
OpenElementDirsConfigThe function-page descriptor the pipeline reads (`module.default.openElementPage` with `kind: 'function-page'`): same metadata/projector shape as {@link OpenElementPageDescriptor} plus the compiled component function — no element class exists, so the generated entry registers nothing and renders through the render function.
OpenElementFunctionPageDescriptor<Data, Params>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.
OpenElementHeadConfigOne structured `<script src>` descriptor accepted by `head.scripts`.
OpenElementHeadScriptLocale configuration for a locale-prefixed build.
OpenElementI18nConfigNot-found signal thrown from a loader to render the route's 404 path.
class OpenElementNotFound extends OpenElementErrorThe 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.
OpenElementPageDescriptor<Data, Params>Redirect signal thrown from a loader/action to short-circuit rendering with an HTTP redirect.
class OpenElementRedirect extends OpenElementErrorHost-agnostic request context shared by App request adapters.
OpenElementRequestContext<Env>Overrides accepted by an `openelement.config.ts` file (unknown keys fail closed).
OpenElementUserConfigA compiled element class carrying the page descriptor static.
PageComponentConstructor<Data, Params>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.
PageErrorProjector<Data, Params>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.
PageHeadResolves a page's head from the request-scoped context (#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.
PageHeadResolver<Data, Params>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).
PagePropsContext<Data, Params>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 renderToString() props (server) or pre-connect property sets (SPA).
PagePropsProjector<Data, Params>Media type of the RFC 9457 action error channel (#863).
"application/problem+json"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.
ProblemDetailsDefault 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.
(context: { params?: Record<string, string>; data?: unknown; }): Record<string, unknown>Throw an {@linkcode OpenElementRedirect} for `location` (status must be a real 3xx).
(location: string | URL, status?: number): neverResolve `dirs` to the three absolute-in-project roots the scanner reads. Omitted entries take the documented defaults.
(dirs: OpenElementDirsConfig | undefined): { routes: string; islands: string; components: string; base: string; }A compiled server page component function (alpha15 server lane): the route module's exported TSX component after the server component lane compiled it — props in, final HTML out. While authoring, the TSX function's inferred type is JSX.Element-returning (the compiler owns the body), so this type admits every function shape; the runtime discriminant in definePage() is the authority on which branch a value takes.
ServerPageComponentCanonical request-time/SSG server route context.
ServerRouteContext<Env, Platform, 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().
ServerRouteMetadataOne 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.
StructuredDataEntryRun the production build and exit with the build's verdict. Shared by the `openelement build` bin subcommand (cli.ts) and this module's own main block, so both faces behave identically.
(argv?: string[]): Promise<void>Run the serve CLI with the arguments that follow the command (the bin's `start` subcommand passes them through verbatim, so `--mode=preview` reaches the mode parser unchanged). Shared by the `openelement` bin (cli.ts) and this module's own main block.
(argv: string[]): Promise<void>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).
ClientScriptDescriptorOne <link rel="alternate"> record, typically carrying an hreflang.
PageHeadAlternateA 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.
ResolvedDocumentA normalized <link> the serializers emit into <head>.
ResolvedDocumentLinkResolves 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.
(head: PageHead | PageHeadResolver | undefined, context: PagePropsContext, clientScripts?: readonly ClientScriptDescriptor[]): ResolvedDocumentWraps a WinterCG handler in a Hono app: every method and path delegates to the handler with the host's env binding and — when the host runtime provides one — its execution context. The generated entry's `openElementRuntimeAdapter` and default export plug in unmodified: ```ts import { createHonoAdapter } from '@openelement/router/hono'; import openElement from './dist/server/entry.js'; const app = await createHonoAdapter(openElement); export default app; ```
(handler: WinterCgHandler): Promise<object>The WinterCG request handler the generated entries export.
WinterCgHandlerMount after host middleware/routes; unmatched URLs continue to the host.
(records: readonly HttpRouteRecord[], options?: RouteTableOptions & { methodNotAllowed?: (request: Request, allow: readonly string[]) => Response | Promise<Response>; }): (request: Request, next: () => Promise<Response>…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.
HttpHandlerRoute-scoped request context handed to every {@link HttpHandler}.
HttpRouteContextA 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.
HttpRouteRecordAttach 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
<Data = unknown, Params extends Record<string, string> = Record<string, string>>(tag: string, componentClass: CustomElementConstructor, descriptor?: LitPageDescriptorInput<Data, Params>): LitPageConstructor<Data, Params>A LitElement page class carrying the page descriptor and its host tag.
LitPageConstructor<Data, Params>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.
OpenElementPageDescriptor<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, props, }: { tag: string; props?: Record<string, unknown>; }): { html: string; }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.
<Env extends Record<string, unknown> = Record<string, unknown>>(options: OpenElementNitroMountOptions<Env>): (event: NitroRequestEvent<Env>) => Promise<Response>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.
NitroRequestEvent<Env>Options for mounting an OpenElement request handler under a Nitro/Node server.
OpenElementNitroMountOptions<Env>Convert the framework's Hono-style route dialect to WHATWG URLPattern syntax.
(path: string): stringOne 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.
RouteMatch<T>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`.
RouteRecordThe 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.
RouteResolution<T>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.
class RouteTableConstruction options: a URL prefix every route is mounted under, and whether a trailing slash is significant.
RouteTableOptionsThe matcher surface a client route list compiles to: matching, resolution and candidate count.
CompiledRouteMatcherCompile a client route list into the canonical {@link RouteTable} matcher, with no router instance attached.
(routes: RouteConfig[]): CompiledRouteMatcherCreate 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`.
(options: RouterOptions): RouterInstanceMatch a route through the canonical RouteTable.
(pathname: string, search: string, routes: RouteConfig[]): RouteMatch<RouteConfig> | nullOne 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.
RouteConfigA live client router: the navigation entry points, the current match (`currentPath`/`currentRoute`/`params`/`searchParams`), and `dispose()` to release its listeners.
RouterInstanceNavigation strategy: the History API ('history'), the URL hash ('hash'), or file-protocol auto-detection ('auto').
RouterModeRequest 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.
"x-openelement-action"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.
(context: OpenElementRequestScope, routePath: string, error: unknown, production: boolean): ResponseWhat one protocol run hands back to the generated handler.
ActionExecutionThe load context the generated handler built; actions receive it plus `formData`.
ActionLoadContextThe 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.
ActionProtocolStateThe 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).
(context: OpenElementRequestScope, location: string, isFetch: boolean): ResponseA fn-form API handler: the `(ctx) => Response` form an API route module default-exports.
ApiRouteFunctionInstantiates 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.
(policyTemplate: string, nonce: string): stringStartup 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.
(module: unknown, route: string, file: string, manifest: StreamRouteManifestLike | undefined): voidStartup 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.
(module: unknown, route: string, file: string): voidThe scope accessor the generated handlers and built-in middleware share.
(request: Request): OpenElementRequestScope | undefinedOptions for {@linkcode createCorsMiddleware} — the surface the generated entry emits.
CorsOptionsThe default body-limit handler 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. Runs as the first element of the generated POST handler chain (`(request, route, next)` — the {@link HttpHandler } shape of
(maxSize: number): (request: Request, route: unknown, next: () => Promise<Response>) => Promise<Response>The CORS middleware: non-preflight requests get the allow-origin (and credentials/expose) headers on the channel and an appended `Vary: Origin` when the origin is not `*`; an `OPTIONS` preflight short-circuits with 204 and the full allow set. The origin resolver may return undefined to deny — the generated default reflects only localhost origins and denies everything else.
(options?: CorsOptions): WinterCgFetchMiddlewareCreates 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` request-scope variable.
(): stringAssembles the generated 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.
(config: GeneratedAppConfig): GeneratedAppBinds the layout runtime to the entry's renderer, trust boundary, and serialized layout/nav/locale data. The entry destructures `{ resolveLayout: __resolveLayout, renderLayout: __renderLayout }`.
(deps: LayoutRuntimeDeps): LayoutRuntimeThe lit renderer (#1339): render a registered LitElement page host to DSD HTML through
(deps: LitPageRendererDeps): PageSsrRendererLogs `<-- METHOD /path` before the chain and `--> METHOD /path 200 12ms` after it, with the elapsed time humanized the way the previous built-in logged it. No color support: the color policy read `process.env`, which shipped runtime code must not (P3).
(options?: LoggerOptions): WinterCgFetchMiddlewareThe 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 per-request scope bound by the WinterCG composition layer so the WinterCG-side middleware can answer through the scope's text channel with the channel headers merged in.
(): (request: Request, allow: string[]) => ResponseThe 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).
(deps: NativePageRendererDeps): PageSsrRendererCreates 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.
(paths: readonly string[]): Record<string, Record<string, unknown>>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).
(deps: PagePropsRuntimeDeps): PagePropsRuntimeReads the inbound request id (honoring it only when it is present, ≤ `limitLength`, and free of characters outside `[A-Za-z0-9_-=]`), regenerates otherwise, exposes it as the `requestId` scope variable and the response header — the request-id header rides every response the scope builds.
(options?: RequestIdOptions): WinterCgFetchMiddlewareCreates one per-request scope. Exported for the generated wiring's test harnesses; {@linkcode WinterCgApp.fetch} creates and binds one per dispatch.
(request: Request, env?: Record<string, unknown>, platform?: unknown): OpenElementRequestScopeThe security response headers, applied after the response exists so a handler cannot skip them, plus `X-Powered-By` removal. Same names and values (and the same disabled `Cross-Origin-Embedder-Policy` default) as the built-in set they replace.
(): WinterCgFetchMiddlewareBinds 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).
(escapeHtml: (value: string) => string): StatusHtmlRendererBinds 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.
(config: StreamBodyConfig): StreamBodyFnCreates 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.
(route: string): ResponseHeaderChannelThe 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 `createStreamShellExecutor` import; the returned gate is the `__createStreamPageShell` call site (Amendment 1 — the last runtime function body that stayed emitted for its oracle pin).
(config: StreamPageShellConfig): (route: string, routeModule: unknown, props: unknown, instanceId: string, documentToken: string, documentStyles?: DocumentStyleSink) => Promise<StreamExecutorView>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.
(original: Request): StreamRequestScopeCreates the internal WinterCG app one generated entry assembles. The dispatch builds lazily on the first fetch (registration happens at module scope) and rebuilds if anything registers afterwards.
(): WinterCgAppObject prototype keys that must never be injected from untrusted props.
ReadonlySet<string>Everything the generated entry destructures and re-exports.
GeneratedAppThe route-descriptor data the generated entry hands the factory.
GeneratedAppConfigThe 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.
GeneratedPageRuntimeInstalls 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.
(): SsrRegistryGuardTrue when the dispatch is an 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.
(env: unknown): booleanThe layout runtime bound into the generated entry.
LayoutRuntimeWhat {@linkcode createLayoutRuntime} binds: the entry's Element imports plus its serialized plan data.
LayoutRuntimeDepsThe subset of
LitPageRendererDepsPath-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).
(locales: readonly string[], path: unknown, fallback: string): stringLayout 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.
(href: string, locale: string, defaultLocale: string): stringOptions for {@linkcode createLoggerMiddleware}.
LoggerOptionsHono-compatible middleware-scope matching: `'/p/*'` matches `/p` itself and everything beneath it; `'/*'` matches everything; a bare `'/p'` matches only `/p` exactly.
(pattern: string, pathname: string): booleanMerges 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).
(response: Response, channel: Headers): ResponseThe subset of the Element serializer the native renderer needs.
NativePageRendererDepsThe per-request scope: one instance per dispatch, bound to its request by the identity registry. Response headers written before the response exists (`header()`) flow into every response the scope constructs — the merge point the Hono context's prepared headers used to own.
OpenElementRequestScopeThe request-scoped page context the generated handlers build for one render (#1326).
PageContextCanonical 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.
(routeModule: unknown): PageDefinitionThe page descriptor a definePage/defineLitPage route module carries on its default export.
PageDefinitionThe 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.
PagePropsRuntimeThe binding the generated-app factory hands {@linkcode createPagePropsRuntime}.
PagePropsRuntimeDepsThe generated entry's `__ssr` binding: render one registered host tag to HTML. `depth` bounds nested island expansion; `projectedChildren` claims external content (the layout slot). Fails closed per the forks below.
PageSsrRendererSource metadata the serializer attributes to a render (the `{ route }` seam).
PageSsrSourceInfoTrusted parent-owned light children keyed by slot name (the shell slot claim).
ProjectedChildrenThe projected props record handed to the compiled page host.
ProjectedPropsHeaders 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.
ReadonlySet<string>The server function page render seam (alpha15 server lane). A function-page descriptor's `render` is the compiled server constructor function (the component lane lowered the authored TSX into `__h`/`__t` composed code) — props in, final HTML out. Two boundary checks live here because this is the ONE place loader-projected props meet the compiled render: - the render must be a function (`OE_PAGE_FUNCTION_RENDER`) — a descriptor whose render never went through the compiler has nothing to call; - the props must NOT carry the reserved `children` key (`OE_PAGE_FUNCTION_PROPS`). The compiled `props.children` channel is trusted final HTML produced by the COMPILER from a caller's own JSX children (the same trust level as an `__ssr` result); page props come from loader/params data, so a `children` key there is a smuggling attempt and is refused before the render function runs. The render function returns a string (the constructors always do); the type is widened to `unknown` so a hostile loader cannot make this seam trust a descriptor the compiler never produced.
(page: unknown, props: ProjectedProps): stringOptions for {@linkcode createRequestIdMiddleware}.
RequestIdOptionsThe request view the generated wiring binds as `c.req`.
RequestScopeRequestNative 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
(routeModule: unknown, fallbackTag: string): stringLit 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.
(routeModule: unknown, fallbackTag: string): stringThe 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.
ResponseHeaderChannelCanonical 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`.
(routeModule: unknown): Record<string, unknown>A route module namespace as the generated entry imports it (`import * as $route`).
RouteModuleRuns 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).
(context: OpenElementRequestScope, routeModule: unknown, loadContext: ActionLoadContext, renderStatusPage: (title: string, message: string, status: number) => Response, state: ActionProtocolState): Promise<ActionExecuti…The env key the SSG prerender pass sets to `true` on every build-time dispatch (ssg-render.ts passes `{ [SSG_PRERENDER_ENV_KEY]: true }` as the request env). Since #1560 the prerender driver is our own static generator, so the key is owned here — this module is the single source; the build side imports the constant, and no second copy exists to drift.
"OPEN_ELEMENT_SSG_CONTEXT"What the generated entry gets from {@linkcode installSsrRegistryGuard}.
SsrRegistryGuardThe generated entry's `__statusHtml` binding: title/message rendered into a minimal status page.
StatusHtmlRendererThe 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.
stringBinding-time configuration of {@linkcode createStreamBody}.
StreamBodyConfigThe bound streaming body builder the generated handler calls.
StreamBodyFnPer-request inputs of the streaming body builder.
StreamBodyOptionsThe streamed document halves the element `documentStreamParts` produced.
StreamDocumentPartsThe slice of the element stream executor the pump consumes.
StreamExecutorViewOne declared deferred field's settlement record (the pump's queue unit).
StreamFieldRecordThe 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}).
(data: unknown, manifest: StreamRouteManifest): StreamFieldRecord[]The entry bindings the stream-shell gate reads. `streamManifests` is the generated `__streamManifests` build data; the executor creator is the entry's `createStreamShellExecutor` Element import, injected so this module stays free of an Element runtime edge (#1339).
StreamPageShellConfigThe request scope the generated handler builds around a streamed route.
StreamRequestScopeOpaque capability marking HTML the application has explicitly vetted as trusted.
TrustedHtmlValueThe internal WinterCG app: the composition surface the generated entry wires.
WinterCgAppThe dialect-free fetch middleware the whole composition speaks.
WinterCgFetchMiddlewareFile size info for a single artifact
ArtifactInfoBuild 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. KR-15: this is a PRODUCTION build. Vite derives `import.meta.env.PROD` from ambient `process.env.NODE_ENV`, not from `mode`, so a build launched from a test runner (`NODE_ENV=test`) or a dev shell silently emitted a development-semantics SSR bundle — `PROD=false`, so the production error channel stopped scrubbing and SSG 500 details fell back to stack traces (known-reds KR-15, Release P0 Gate). Pin production for the duration of the Vite call and restore the ambient value afterwards, so programmatic callers (and their tests) cannot leak a production NODE_ENV into the rest of the process. `mode` is made explicit for the same reason: the generated `import.meta.env.MODE` should say production even when a caller's ambient environment disagrees.
(config?: InlineConfig): Promise<unknown>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.
(options: FrameworkOptions): HeadExtrasResultFull build manifest summary
BuildManifestLow-level Vite plugin pipeline: SSR dev server, SSG and islands without the content/i18n conveniences of `openElement()`.
(config?: OpenPipelineConfig): Plugin[]Adapter options extend Element options with build-only delivery declarations. The element package remains unaware of Vite/SSG policy.
FrameworkOptionsResult of building head extras from FrameworkOptions.
HeadExtrasResultVite plugin compiling `.mdx` route files into compiled page modules.
(options?: OpenMdxPluginOptions): PluginCreate the full OpenElement Vite plugin set: route pipeline, SSG and islands.
(options?: OpenElementOptions): Plugin[]Blog options stored in the adapter build context.
OpenElementBlogOptionsThe 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.
class OpenElementBuildContextMinimal build-context contract available to adapter sub-plugins.
OpenElementBuildContextLikeLocale options carried through the build context to the i18n integration.
OpenElementI18nContextOptionsProject 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 layout navigation. Absent means a single-locale site with no locale prefixing — the pre-i18n output, byte for byte.
OpenElementI18nOptionsOptions 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`), while a config file's `dirs` block is the spelling that also moves the file conventions.
OpenElementOptionsOptions for the `.mdx` route plugin ({@linkcode mdxPlugin}).
OpenMdxPluginOptionsLow-level Vite plugin pipeline: SSR dev server, SSG and islands without the content/i18n conveniences of `openElement()`.
(config?: OpenPipelineConfig): Plugin[]Options for the low-level {@linkcode openPipeline} Vite plugin pipeline.
OpenPipelineConfigThe resolved preset options: the declared style sources, in order.
ResolvedTailwindOptionsSpeculation Rules configuration for SSG post-processing
SpeculationRulesOptionsUser-facing SSG build behavior switches (OpenElementOptions['ssg']).
SsgBehaviorOptionsOptions for the opt-in Tailwind entry (alpha15 S lane; the pre-S "preset" compiled the sources itself — this shape only declares them). `tailwind: true` enables the entry with no declared sources: the document stylesheet is Tailwind's own default compile (`@import 'tailwindcss'`). The shape lives here, on the host-neutral config surface, and the Vite build layer consumes it — the Framework-root declaration graph packed consumers typecheck must never name `vite` (the packed-consumer gate's declaration leak pattern).
TailwindOptions@openelement/create
5 个导出The dist-tag a versionless documented install resolves: npm's scope alias defaults to `latest`, which the 1.0 line rides since the alpha.11 ruling. The exact version is registry truth; the canonical spelling names no tag.
"latest"The scope `npm create` resolves to {@linkcode CREATE_PACKAGE_SPECIFIER}: npm's initializer alias maps a bare `@scope` (optionally `@scope@<tag>`) to `@scope/create` at the same tag — untagged, at the scope's default dist-tag — so the canonical spelling never repeats the `/create` suffix (owner-verified against npm's init alias rules).
"@openelement"The npm specifier the generator is published under.
"@openelement/create"Placeholder the usage text and the docs use in place of a project name.
"<project-name>"The documented install command shapes, all verified against the published two-bin artifact (bins `openelement-create` and `create-openelement`, both `src/cli.js`; npm 11 / pnpm 12): - canonical: `npm create
(projectName?: string, options?: { tag?: string; }): string@openelement/ui
19 个导出The build-time generated package manifest (declarations for every UI component).
OpenElementPackageManifestButton or link control: an `href` property switches the compiled anchor branch (no-JS navigation survives SSR), `variant`/`size` pick the styled surface, and the disabled state follows the reflected host attribute.
class OpenButton extends OpenElementCode block with a copy button.
class OpenCodeBlock extends OpenElementDialog component using native <dialog> element + popover API.
class OpenDialog extends OpenElementPopover-API dropdown with CSS Anchor Positioning placement.
class OpenDropdown extends OpenElementForm-associated text input with a label, an inline error slot, and native constraint validation (required → valueMissing via setValidity).
class OpenInput extends OpenElementTheme toggle button for dark/light mode: reads and flips the document's `data-theme` (with an initialization priority chain) and persists the choice; icon visibility follows the current theme attribute.
class OpenThemeToggle extends OpenElementRead the host's `key` slot, initializing it with `init()` on first use.
<T>(host: object, key: string, init: () => T): TExplicitly register every first-party UI element. Safe to call repeatedly.
(registry?: CustomElementRegistry | undefined): voidOverwrite the host's `key` slot.
(host: object, key: string, value: unknown): voidRead the host's `key` slot, initializing it with `init()` on first use.
<T>(host: object, key: string, init: () => T): TOverwrite the host's `key` slot.
(host: object, key: string, value: unknown): voidThe build-time generated package manifest (declarations for every UI component).
OpenElementPackageManifestButton or link control: an `href` property switches the compiled anchor branch (no-JS navigation survives SSR), `variant`/`size` pick the styled surface, and the disabled state follows the reflected host attribute.
class OpenButton extends OpenElementCode block with a copy button.
class OpenCodeBlock extends OpenElementDialog component using native <dialog> element + popover API.
class OpenDialog extends OpenElementPopover-API dropdown with CSS Anchor Positioning placement.
class OpenDropdown extends OpenElementForm-associated text input with a label, an inline error slot, and native constraint validation (required → valueMissing via setValidity).
class OpenInput extends OpenElementTheme toggle button for dark/light mode: reads and flips the document's `data-theme` (with an initialization priority chain) and persists the choice; icon visibility follows the current theme attribute.
class OpenThemeToggle extends OpenElement应用选项类型，逐成员一行。
stringDocument title; defaults to the package.json `name`.
string`<meta name="description">` + `og:description`.
string`<html lang>`; defaults to `en`.
stringSite-root-relative favicon path, emitted as `<link rel="icon">`.
string`og:image` URL. Absolute (crawlable) or site-root-relative.
string[]External stylesheets linked into `<head>`.
OpenElementHeadScript[]External scripts emitted into `<head>`; inline code is not accepted here.
"fail" | "warn"Policy for dynamic-route render failures during SSG. See {@link SsgRenderOptions.dynamicRouteFailure}.
"native" | "lit"Page renderer selection (Beta.2.2, #1339). EXPLICIT, never inferred: 'native' (default) renders pages through the compiled Part Program serializer (renderToString); 'lit' renders LitElement pages through
stringDirectory the route scanner walks, relative to the Vite root. Defaults to `app/routes`.
stringDirectory island modules are discovered in. Defaults to `app/islands`.
string[] | "auto" | "manual"How the build admits component packages whose modules the application imports. - omitted or `'auto'` (the default): the scan derives the admitted set at scan time — every package-owned element module the app's routes, pages, layouts, islands and components really reach (bundler-resolved) is attributed to its owner package (nearest `package.json`), and a package with a valid OpenElement manifest i…
LayoutConfigLayout declaration; `false` disables the layout, `'default'` uses the built-in one.
LayoutsConfigNamed layout declarations keyed by layout name.
string@dangerous injected as-is, only use with controlled content
(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.
(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.
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>`.
(string | RegExp)[]"load" | "idle" | "visible" | "only" | "none"stringOutput directory for the build artifacts. Defaults to `dist`.
{ 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.
booleanEnable the View Transitions API for client navigations. Defaults to true.
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.
booleanBuilt-in CORS middleware. Default-ON; pass `false` to disable.
string | string[]Static CORS allowlist data, serialized into the generated entry as JSON. Mutually exclusive with {@link FrameworkOptions.middleware.corsOriginModule }.
stringPath 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 `layout.import` (e.g. './app/cors-origin.ts'). Mutually exclusive with `corsOrigin`.
booleanEmit and honor a per-request id header. Default-ON; pass `false` to disable.
booleanLog each request through the built-in logger. Default-ON; pass `false` to disable.
booleanAttach the built-in security response headers. Default-ON; pass `false` to disable.
{ policy?: string; nonce?: boolean; reportOnly?: boolean; }Content-Security-Policy emission: the policy string, nonce generation, and report-only mode.
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 `layout.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 configured…
CriticalFontAsset[](string | CriticalStyleAsset)[](string | CriticalStyleAsset)[]Alias for styles accepted by config producers.
(string | CriticalInlineScriptAsset)[]booleanAllow intentional external render-blocking styles/scripts.
booleanAlias retained only within this build-side config shape.
booleanMinify inline CSS. Defaults to true.
stringOrigin used to distinguish same-origin and cross-origin absolute URLs.
CriticalAssetsOptionsOpenElementI18nOptionsboolean | TailwindOptionsOpt-in Tailwind entry (alpha9 C2, #1505; externalized alpha15 S lane). `true` or an options object declares the style sources that compile through the official `@tailwindcss/vite` pipeline into the linked document stylesheet; absent keeps the build byte-identical to a Tailwind-less pipeline.
boolean | UnocssOptionsOpt-in UnoCSS entry (alpha15 stage 2B): the sibling of `tailwind`, same shape and same meaning. Declaring it selects UnoCSS as this application's style engine; declaring both keys is a conflict and fails closed — see `UnocssOptions` (`@openelement/router/vite`).
来自编译器 manifest 的 Custom Element。
Button or link control: an `href` property switches the compiled anchor branch (no-JS navigation survives SSR), `variant`/`size` pick the styled surface, and the disabled state follows the reflected host attribute.
@openelement/ui/open-buttonCode block with a copy button.
@openelement/ui/open-code-blockDialog component using native <dialog> element + popover API.
@openelement/ui/open-dialogPopover-API dropdown with CSS Anchor Positioning placement.
@openelement/ui/open-dropdownForm-associated text input with a label, an inline error slot, and native constraint validation (required → valueMissing via setValidity).
@openelement/ui/open-inputTheme toggle button for dark/light mode: reads and flips the document's `data-theme` (with an initialization priority chain) and persists the choice; icon visibility follows the current theme attribute.
@openelement/ui/open-theme-toggle