@geastack/compiler 1.0.15

package/dist/plugins/gea/host.d.ts

@@ -0,0 +1,520 @@
+import type { HostCallSpelling, HostConstructorTable, HostMemberTable } from '../../targets/cpp/host/host-members.js';
+/**
+ * The one field of `HostShimDefinitions` this compiler reads, as this compiler
+ * needs it.
+ *
+ * Deliberately NOT `import type { HostShimDefinitions } from
+ * '@geastack/geatsc-plugin-gea'`: a static type import makes the framework
+ * package a hard build dependency of the compiler, and this load is a `require`
+ * in a `try` precisely so it is not one. Restating the *shape of the one field
+ * read* is not restating the data -- the 39 entries stay in the package, which
+ * is the whole point -- and the narrowing below is what makes the boundary
+ * honest rather than asserted.
+ */
+/** One member binding, as the package states it: the spelling, and every receiver type it accepts. */
+export interface GeaMemberBinding {
+    readonly emit?: string;
+    readonly receiverTypes?: readonly string[];
+    /**
+     * The C++ this binding's `emit` actually evaluates to, stated by the package
+     * because the DECLARED type (`index.d.ts`'s ambient interfaces) is
+     * sometimes not it -- `OscillatorNode.connect` is declared to return
+     * `AudioDestinationNode` (the Web Audio spec's chaining convention) and the
+     * real `gea::host::OscillatorNode::connect` is `void`. Read only for the
+     * literal string `"void"`: see `geaHostMemberVoidResults`, members.ts.
+     */
+    readonly returnType?: string;
+}
+interface GeaHostShimSlice {
+    readonly nativeTypes: Readonly<Record<string, string>>;
+    /**
+     * `new <AmbientConstructor>(...)` spellings, keyed by the ambient
+     * CONSTRUCTOR interface's own declared name (`AudioConstructor`, one level
+     * up from the instance name `nativeTypes` carries). See `geaHostConstructors`
+     * (below) for how this becomes a `HostConstructorTable`, and the package's
+     * own `types.ts` doc comment on this field for why it is keyed this way.
+     */
+    readonly nativeConstructors?: Readonly<Record<string, string>>;
+    readonly nativeMemberMethods?: Readonly<Record<string, readonly GeaMemberBinding[]>>;
+    readonly nativeMemberPropertyGetters?: Readonly<Record<string, readonly GeaMemberBinding[]>>;
+    readonly nativeMemberPropertySetters?: Readonly<Record<string, readonly GeaMemberBinding[]>>;
+    readonly nativeDocumentMethods?: Readonly<Record<string, {
+        readonly emit?: string;
+    }>>;
+    /** Intrinsic tags whose single-text-run form is a text node -- see `geaElementTextLeafTags`. */
+    readonly elementTextLeafTags?: readonly string[];
+    /**
+     * Methods the host adds to a DOM ELEMENT -- one row, `getContext`.
+     *
+     * Read for the member name only. The spelling calls into `gea_ir::`, which
+     * this compiler does not generate; what the wrapper does is stated by the
+     * engine instead. See `geaCanvasAcquisition`.
+     */
+    readonly domElementMethods?: Readonly<Record<string, string>>;
+    /**
+     * Global VALUES a host holds one instance of and reaches by a fixed C++
+     * spelling -- `navigator`, `window`, `localStorage` -- stated separately from
+     * `hostNamespaces` because a name here is not necessarily also a PATH: a
+     * program may hold `navigator` itself (`navigator`/`window` state both,
+     * deliberately), while `localStorage` states only this one, its every member
+     * still reached through `hostNamespaceMethods`' identical path-call
+     * mechanism. See `geaHostNamespaceRoots`.
+     */
+    readonly hostGlobalObjects?: Readonly<Record<string, string>>;
+    /**
+     * The C++ TYPE of each `hostGlobalObjects` value, keyed by the same global
+     * name -- `window` -> `gea::host::WindowFacade` for the `inline constexpr
+     * WindowFacade window{}` that `hostGlobalObjects.window` spells.
+     *
+     * The two tables answer different questions and neither derives the other:
+     * `localStorage`'s object is `gea::host::Storage` and its type is
+     * `gea::host::StorageFacade`. See `geaHostNamespaceRootTypes`.
+     */
+    readonly hostGlobalObjectTypes?: Readonly<Record<string, string>>;
+    readonly hostNamespaces?: Readonly<Record<string, string>>;
+    readonly hostNamespaceMethods?: Readonly<Record<string, Readonly<Record<string, string>>>>;
+    /**
+     * The same members, stated NATIVELY: a call template plus the C++ type the
+     * call yields. The package writes these where the boxed spelling would lose
+     * the result's type -- `image.make(id)` yields a `GeaEmbeddedImage` handle,
+     * `image.readFile` a `std::vector<std::uint8_t>` rather than a per-byte boxed
+     * record.
+     *
+     * Read as the table that WINS where both state a member: this one can place
+     * the call inside something else, and `hostNamespaceMethods` -- a bare C++
+     * path with the arguments appended -- structurally cannot. See
+     * `geaHostNamespaceMethods` for the precedence and its measured blast
+     * radius; the short version is that 21 of the 25 rows here agree with their
+     * bare twin exactly (`gea::host::Battery.level` versus
+     * `gea::host::Battery.level({args})`) and render identically either way, so
+     * the precedence is only observable on `navigator.mediaDevices.getUserMedia`
+     * and on the three rows -- `image.make`, `http.createServer`, `http.close` --
+     * that no other table states at all.
+     */
+    readonly nativeNamespaceMethods?: Readonly<Record<string, Readonly<Record<string, {
+        readonly emit?: string;
+        readonly returnType?: string;
+    }>>>>;
+    readonly hostNamespaceProperties?: Readonly<Record<string, Readonly<Record<string, string>>>>;
+    /**
+     * Which namespace properties are backed by an ACCESSOR, as a name set per
+     * namespace -- `{ Display: ['ctx', 'width', ...] }`, not a spelling table.
+     * The spelling is already in `hostNamespaceProperties`; this states that
+     * reading it means CALLING it.
+     */
+    readonly hostNamespacePropertyAccessors?: Readonly<Record<string, readonly string[]>>;
+    readonly hostNamespacePropertySetters?: Readonly<Record<string, Readonly<Record<string, string>>>>;
+    readonly embeddedHostFunctions?: Readonly<Record<string, string>>;
+    readonly embeddedHostConstants?: Readonly<Record<string, {
+        readonly emit?: string;
+    }>>;
+    readonly hostExternDeclarations?: Readonly<Record<string, readonly string[]>>;
+    /**
+     * The 2D canvas context's members, keyed by name, each stating the package's
+     * own `gea_ir::canvas<Member>` wrapper.
+     *
+     * Read for the member NAMES and for the engine method each wrapper is named
+     * after -- see `geaCanvasMembers`. The templates themselves are not usable
+     * here: they call into a namespace the package generates from a v1 IR bundle
+     * this compiler does not produce.
+     */
+    readonly canvasContextMethods?: Readonly<Record<string, string>>;
+    /** The same, for the context's settable properties (`fillStyle` -> `gea_ir::canvasSetFillStyle`). */
+    readonly canvasContextPropertySetters?: Readonly<Record<string, string>>;
+    /**
+     * How the host constructs its own classes -- `new WebSocket(url)`,
+     * `new MediaStream()` -- read by `geaHostConstructors` (constructors.ts).
+     * See `GeaHostClass` for what one row states.
+     */
+    readonly embeddedHostClasses?: Readonly<Record<string, GeaHostClass>>;
+}
+/**
+ * One host class's construction convention, exactly as the package states it.
+ *
+ * Two conventions, because the host builds its classes two different ways.
+ * `construct` is the whole `new C(...)` expression already assembled --
+ * `gea::host::MediaStream({args})` -- for a class whose C++ constructor takes
+ * the arguments directly. `factory` is a thunk that returns a handle as a
+ * `double`, for a class built from a free function instead of a constructor
+ * call (`gea::host::websocket::create_handle`); `wrapper` names the C++ type
+ * that handle is wrapped in to become the value. A row with neither states no
+ * construction at all, deliberately -- `hostConstructors` cannot invent one.
+ */
+export interface GeaHostClass {
+    readonly wrapper?: string;
+    readonly construct?: string;
+    readonly factory?: string;
+}
+/**
+ * The host type table, from the package that owns it.
+ *
+ * gea ships its declarations, its native implementation and this table
+ * together; the table is that package's statement about its own runtime, and a
+ * copy of it here would be a second authority that drifts the first time the
+ * runtime changes. So it is loaded, not restated.
+ *
+ * `require` rather than `import()`: this package is ESM, and Node's
+ * `require(esm)` (>= 22.12; this repo runs 24) resolves it synchronously, so
+ * `compile()` stays synchronous end to end and no caller has to await a plugin
+ * before compiling. A module graph with a top-level `await` would not load this
+ * way, and the `catch` below is what that fails into.
+ *
+ * `GEATSC2_GEA_PLUGIN` overrides the specifier with an explicit path -- how a
+ * different build of the plugin is measured against this compiler, and the only
+ * way an absolute path ever enters this decision.
+ *
+ * Two failures, told apart. The package simply not being installed is a
+ * configuration, not a defect: the table is empty, the plugin claims nothing
+ * but `jsx-element@1`, and every non-gea program compiles exactly as it did. A
+ * package that IS installed but does not answer -- a load error, a missing
+ * factory, a table that is not string-to-string -- is a defect, and it throws.
+ *
+ * That distinction is the whole point. Swallowing the second case returns an
+ * empty table indistinguishable from the first, so every gea program loses
+ * every carrier at once and is refused for obligations spelled in TypeScript
+ * names (`Document@1`) that nothing was ever going to claim -- a fail-open that
+ * reads as a compiler bug for as long as it takes to notice the plugin never
+ * loaded. A compiler that substituted a built-in table here would be back to
+ * hand-maintaining the data; one that quietly substituted an empty one is
+ * worse, because it looks like it read the data and disagreed.
+ */
+export declare const geaNativeTypes: () => ReadonlyMap<string, string>;
+/** The member tables, exactly as the package states them; `null` when the package is not installed. */
+export declare const geaMemberTables: () => GeaHostShimSlice | null;
+/**
+ * The global names that are host namespaces rather than values.
+ *
+ * `deviceInfo` is not an object the program can hold: every use of it is a
+ * path to a C++ spelling, and the value itself never exists at run time. The
+ * table's own value -- the C++ prefix -- is deliberately not what this compiler
+ * keys by, because the member tables are keyed by the PROGRAM's path
+ * (`deviceInfo.deviceId`, `navigator.bluetooth.keyboard.tap`), and following the
+ * program's spelling is what makes a nested namespace one lookup rather than a
+ * translation step that could disagree.
+ *
+ * `hostGlobalObjects` names join this set too, but only the ones the package
+ * ALSO states members under (`hostNamespaceMethods.localStorage.*`, etc): the
+ * same "a path cannot be a namespace here and have no members there" rule
+ * `targets/cpp/host-members.ts`'s `isHostNamespacePath` already applies to
+ * every nested path, asked here of a top-level one. `localStorage` states
+ * only `hostGlobalObjects` -- unlike `navigator`/`window`, which state both,
+ * because a program may also want to HOLD one of those as a value -- but every
+ * one of its members (`gea::host::Storage.getItem`, `.setItem`, ...) is
+ * already spelled the same fixed-path-call shape `Display`'s are, with no
+ * `{receiver}` slot, so it is a namespace root by the identical test. Without
+ * this a `localStorage.getItem(...)` census-admitted `GeaLocalStorage` as an
+ * ordinary host protocol needing its own native boundary, when the host
+ * states no carrier for that name at all -- only for the global itself, under
+ * a different table.
+ */
+export declare const geaHostNamespaceRoots: () => ReadonlySet<string>;
+/**
+ * The C++ type of the one object a host holds behind a namespace root.
+ *
+ * A root is a PATH, not a cell: `window.innerWidth` renders
+ * `gea::host::window.innerWidth()` and no object named `window` is ever
+ * materialized. But a path is not nothing either -- `gea::host::window` is a
+ * real `inline constexpr WindowFacade`, and this is the package saying so.
+ * Without it, a compiler asked what carries the ambient `window` has only its
+ * lib.dom declaration to answer from, and expands `Window & typeof globalThis`
+ * into a struct of its own.
+ *
+ * Restricted to names that really are roots (`geaHostNamespaceRoots`): the
+ * package's own table is keyed by global name, and a global it states a type
+ * for but no members under is a VALUE this compiler already places as a host
+ * constant or singleton -- claiming a path carrier for one would be a second
+ * authority over a name the first already answered.
+ */
+export declare const geaHostNamespaceRootTypes: () => ReadonlyMap<string, string>;
+/**
+ * What each namespace member renders to when it is CALLED.
+ *
+ * Both tables the package states, the NATIVE one first: where a member appears
+ * in both, the native row is the one that survives.
+ *
+ * The two tables are not two spellings of one fact. `hostNamespaceMethods`
+ * states a bare C++ path, which can only ever be called -- append arguments and
+ * that is the whole call. `nativeNamespaceMethods` states a TEMPLATE, which can
+ * also place the call inside something else, and the package writes one exactly
+ * where the bare path would lose the result's type: `getUserMedia` is
+ * `gea::host::MediaStream(gea::host::media::get_user_media_audio({args}))`,
+ * because the underlying host function hands back an opaque handle id and the
+ * `MediaStream` is what the program was promised.
+ *
+ * Precedence used to run the other way, with the bare row winning and the
+ * template admitted only when it reduced to a bare path (`gea::host::image.make
+ * ({args})` does; the `MediaStream` wrapper does not). That is the two-authority
+ * failure in its silent form: both tables answered, the LESS informative answer
+ * won, and the loss showed up three layers later as a `unsigned int` assigned
+ * into a `gea::Promise<gea::host::MediaStream>` that clang refused. A table that
+ * states more cannot be outranked by one that states less.
+ *
+ * Measured blast radius, against the package as it ships: 25 native rows, 21 of
+ * which agree with their bare twin exactly (`gea::host::Battery.level` versus
+ * `gea::host::Battery.level({args})`) and render identically either way. Of the
+ * remaining four, three are members the bare table does not state at all, and
+ * `navigator.mediaDevices.getUserMedia` is the single row where the two really
+ * disagree -- so flipping the precedence changes exactly the one call this
+ * exists to fix, plus `http.createServer`, which no table could reach before
+ * because its template does not reduce.
+ */
+export declare const geaHostNamespaceMethods: () => ReadonlyMap<string, HostCallSpelling>;
+/**
+ * What each namespace member renders to when it is READ.
+ *
+ * `hostNamespaceProperties` alone, with `()` appended for every member the
+ * package also names in `hostNamespacePropertyAccessors`. That second table is
+ * a name SET, not a spelling table -- `{ Display: ['ctx', 'width', ...] }` --
+ * and what it states is that the C++ behind the spelling is a member function:
+ * `DisplayFacade::ctx()` and `DisplayFacade::width()` really are methods, so a
+ * read that did not call them would name a member function rather than read a
+ * value. v1 answers the same question the same way (`qualified-call` versus
+ * `qualified-value` in `host-runtime-protocol.ts`).
+ *
+ * The SETTER table is deliberately not merged in here. It states a different
+ * spelling for a different operation -- `Display.orientation` reads
+ * `gea::host::Display.orientation()` and writes
+ * `gea::host::Display.setOrientation` -- and every one of its 12 rows collides
+ * with a read row, so merging made the setter win and turned every one of those
+ * reads into a reference to the setter. It is its own table instead, right
+ * below (`geaHostNamespacePropertySetters`), for the write side of exactly
+ * this same member -- dropping it entirely left a namespace WRITE
+ * (`Display.autoRotate = true`) with nowhere to resolve, so `emitFieldStore`
+ * fell through to the ordinary struct-field path, asked `operandText` for a
+ * namespace receiver's value, and hit the "host namespace used as a value"
+ * refusal that path states for exactly this reason.
+ */
+export declare const geaHostNamespaceProperties: () => ReadonlyMap<string, string>;
+/**
+ * What each namespace member renders to when it is WRITTEN.
+ *
+ * The write-side twin of `geaHostNamespaceProperties`, over
+ * `hostNamespacePropertySetters` instead of `hostNamespaceProperties`. Every
+ * row here is already a full call spelling -- `gea::host::Display.setAutoRotate`
+ * -- the same shape `hostNamespaceMethods` rows are, so nothing here appends a
+ * trailing `()` the way the read side's accessor rows do: the value argument
+ * fills that call's own parentheses at the write site instead.
+ */
+export declare const geaHostNamespacePropertySetters: () => ReadonlyMap<string, string>;
+/** The host's free functions, by the name the program writes. */
+export declare const geaHostFunctions: () => ReadonlyMap<string, string>;
+/**
+ * `new <AmbientConstructor>(...)` spellings, transposed from the package's own
+ * `nativeConstructors` -- one of the two tables the package states a
+ * construction in, unioned with the other by `geaHostConstructors`
+ * (constructors.ts). This one (keyed by the constructor interface's declared name --
+ * `AudioConstructor`) to a `HostConstructorTable` (keyed by the CARRIER
+ * `nativeTypes` gives that same declared name, falling back to the declared
+ * name itself for a row `nativeTypes` does not also carry -- the identical
+ * fallback `HostConstructorTable`'s own doc comment states, and the same
+ * lookup `nativeHandleInvocationText` performs at the call site:
+ * `callee.native ?? protocol`).
+ *
+ * Arity is never stated by the package: it is counted off the template's own
+ * highest `{argN}` slot (`templateArity`, the same helper `addDocumentRows`,
+ * members.ts, already uses for a template with no receiver), so the arity a
+ * construction is checked against can never drift from the template that
+ * actually renders it.
+ */
+export declare const geaAmbientConstructors: () => HostConstructorTable;
+/** The host's global constants, by the name the program writes. */
+export declare const geaHostConstants: () => ReadonlyMap<string, string>;
+/**
+ * One of the package's templates, as this backend spells its slots.
+ *
+ * The package writes `$receiver` / `$args` / `$value`; `fillHostTemplate` reads
+ * `{receiver}` / `{args}` / `{value}`. Two spellings of the same three slots,
+ * so this is the transposition every other table here already gets -- not a
+ * rewrite of the template, whose text is otherwise carried through unchanged,
+ * comments and all. Shared with `members.ts` so the key a preamble is stored
+ * under and the row it belongs to are the same string by construction.
+ */
+export declare const canvasSlotSpelling: (emit: string) => string;
+/**
+ * The plugin package's own canvas dispatch, as C++ this unit carries.
+ *
+ * Every canvas row states a `gea_ir::canvas*` wrapper, and this is what defines
+ * them: `directCanvasInteropSource`, the same generator v1 emits into every
+ * canvas program. It is called with `boxedValueModel: false`, which drops the
+ * four overloads that exist only to accept geatsc v1's boxed carrier and its
+ * `gea_f32` scalar -- neither type is in a unit this compiler emits -- and
+ * changes nothing else.
+ *
+ * Loaded from a sibling of the shim module, so an explicitly pointed-at build
+ * of the plugin answers both questions. If it cannot answer, that throws: a
+ * package that states canvas MEMBERS but ships no generator for them would
+ * otherwise emit calls to an undefined namespace, and a link error names the
+ * symbol rather than the cause.
+ */
+export declare const geaCanvasInterop: () => readonly string[];
+/**
+ * The declarations a unit must carry before it may name a host spelling.
+ *
+ * Keyed by the spelling, because that is the question: a unit that emits
+ * `gea::host::device_info::deviceId` needs whatever declares it, and a unit that does
+ * not must not carry it. Every row this package states today is the same
+ * guarded `#include "gea/embedded.h"`, but they are stated one per spelling and
+ * are read that way -- collapsing them to a single preamble here would be this
+ * compiler deciding that a fact about 331 symbols is really a fact about one.
+ */
+/**
+ * The guarded `#include "gea/embedded.h"` every one of the package's host
+ * spellings opens with, on its own.
+ *
+ * Taken from the package rather than restated, for the reason `geaHostPreambles`
+ * gives below: one spelling of the engine include in this compilation. A unit
+ * that needs it for a reactive field's cell but names no host spelling has
+ * nowhere else to get it, and one that needs it for both gets the identical
+ * string, so the preamble set collapses the two.
+ *
+ * Empty when the package is absent -- there is then no engine to include, and
+ * no reactive cell either.
+ */
+export declare const geaEmbeddedIncludeGuard: () => readonly string[];
+export declare const geaHostPreambles: () => ReadonlyMap<string, readonly string[]>;
+/**
+ * The host object model gea installs, and the spellings that render it.
+ *
+ * TypeScript has no document. `Document`, `Element` and `HTMLElement` are
+ * declared in `lib.dom.d.ts`, which is a *host's* description of itself, not
+ * the language's -- a generic TypeScript-to-C++ compiler that knew how to
+ * render `document.getElementById` would be asserting something about the
+ * program's environment that nothing in the program says. So the backend does
+ * not know these, and this plugin does.
+ *
+ * The claim and the template live together on purpose. `nativeProtocols` says
+ * which protocols may be read at all and `hostMembers` says what each member
+ * renders to; when those two sit in different layers they become two
+ * authorities over one question, and the way they fail is silent -- preflight
+ * certifies a program on the strength of the claim, and emission then refuses
+ * it by name because the template was never there. Stating both here means a
+ * protocol cannot be claimed without its spelling arriving with it.
+ *
+ * What is deliberately *not* claimed matters as much as what is. Each interface
+ * below is a small, real subset -- the members corpus programs actually call --
+ * rather than the full `lib.dom.d.ts` surface. A member nothing renders is
+ * refused by name at the call site, which is the failure this table exists to
+ * produce instead of a call to a symbol the runtime never declared.
+ */
+export declare const geaHostMembers: HostMemberTable;
+/**
+ * The protocols this plugin's runtime installs.
+ *
+ * `jsx-element@1` is here because JSX is not a TypeScript *value* form at all:
+ * the language parses it and hands back a type the host decides the meaning of,
+ * and the meaning here is this plugin's element. `AudioContext@1` and
+ * `HTMLElement@1` are `lib.dom.d.ts` interfaces on the same footing as
+ * `Document` above.
+ *
+ * `AudioContext@1` claims no members below, on purpose: the protocol is
+ * readable -- a program may hold one and pass it around -- and every call on it
+ * refuses by name, which is the honest state of a boundary whose implementation
+ * is a tag struct and nothing else.
+ */
+export declare const geaNativeProtocols: ReadonlySet<string>;
+/**
+ * The carrier a JSX element value is held in, added to the package's own table
+ * under the protocol's own name.
+ *
+ * `jsx-element@1` is the one protocol this plugin installs that the package
+ * states no row for, because it is not a declared TypeScript type: `JSX.Element`
+ * is an empty interface the language hands back from an element expression, and
+ * what it *is* on this host is an element of the engine's tree -- the same thing
+ * `Element`/`GeaElement` already name. So the spelling is read off the package's
+ * own `Element` row rather than written here: one authority, and a package that
+ * moves its element type moves this with it.
+ *
+ * Without the row the protocol carries `gea::NativeHandle<gea_native_protocol_jsx_element_v1>`,
+ * a tag type with no tree behind it -- C++ that compiles and renders nothing.
+ */
+export declare const geaJsxElementCarrier: () => string | null;
+/**
+ * The engine class a 2D canvas context is held in.
+ *
+ * The second carrier the package states no row for, and for a reason worth
+ * writing down: v1 never needed one. It reaches the canvas through a `gea_ir::`
+ * namespace it GENERATES into each program -- `gea_ir::canvasFillRect(ctx, ...)`
+ * and friends, produced by the plugin package's own `cpp-ir.ts` from a v1 IR
+ * bundle -- so the context's own C++ type is a fact that block knows and the
+ * shim tables never had to. This compiler has no such bundle and emits no such
+ * block: it calls the engine's class directly, and so it has to know what the
+ * class is.
+ *
+ * The name is the engine's own, from `core/packages/engine/ui/canvas_element.h`,
+ * and it is the same one the package's generated block names in the direct
+ * (unboxed) canvas mode `GEA_EMBEDDED_DIRECT_CANVAS_CONTEXT` selects:
+ * `gea::embedded::ui::CanvasElement(node.id()).getContext2D()` yields exactly
+ * this type. It belongs in the package beside the canvas member tables, and it
+ * is here rather than there because adding a `nativeTypes` row changes what v1
+ * does with the name too, and that is not a change this compiler's work should
+ * make on v1's behalf.
+ */
+export declare const geaCanvasContextCarrier = "gea::embedded::ui::CanvasRenderingContext2D";
+/**
+ * The package's table, plus the carriers it states no explicit `nativeTypes`
+ * row for.
+ *
+ * `WebSocket`, `RTCPeerConnection` and `Audio` are the third such case, beside
+ * the two below. The package states these three only in `embeddedHostClasses`
+ * (a `wrapper` to construct, no `nativeTypes` entry), and this is not an
+ * oversight to route around: v1's own compiler resolves a carrier the
+ * identical way, `nativeTypeName(sourceName) ?? embeddedHostClassBindings[
+ * sourceName]?.wrapper` (`nativeCarrierRoles`, `geatsc/src/host-shims/
+ * host-runtime-protocol.ts`), because these three are `lib.dom.d.ts`
+ * `interface X` + `declare var X: { new(...): X }` pairs (not `declare
+ * class`), and this compiler's own `bindNativeType` (`semantics/host-
+ * protocols.ts`) has exactly one lookup for any of them: the flat
+ * `nativeTypes` map, keyed by the declared name. Reading the package's own
+ * fallback here is the transposition this file already performs for every
+ * other table, not a rule invented for these three names.
+ */
+export declare const geaProtocolCarriers: () => ReadonlyMap<string, string>;
+/**
+ * The globals this host holds one instance of and reaches by name.
+ *
+ * `document` is derived, not written: the package ships `nativeDocumentMethods`
+ * -- a member table with no receiver list, every spelling going through
+ * `gea::embedded::ui::Document::instance()` -- and a receiverless member table
+ * for an object IS the statement that the object is reached by name. A package
+ * that stops shipping one stops claiming this, which is the correct answer.
+ *
+ * Left as a value, a read of `document` emitted `extern gea::embedded::ui::Document
+ * document;` (a cell the engine never defines) and copied it into a local of a
+ * type whose default constructor is private.
+ */
+export declare const geaHostSingletons: () => ReadonlySet<string>;
+/**
+ * What `<>...</>` builds on this host, read from the package rather than named
+ * here.
+ *
+ * A fragment has no tag, so there is nothing for the intrinsic recipe to pass
+ * and no way to derive the answer from the syntax. gea's answer is its
+ * document's own `createDocumentFragment`, which the package already ships as
+ * a receiverless document method returning a `NodeHandle` -- the engine's
+ * `Document::createDocumentFragment` (`engine/ui/document.h`), whose node
+ * `appendChild` splices into the parent instead of nesting.
+ *
+ * Reading the package's row rather than writing the call here is the same rule
+ * every other spelling in this file follows: a second copy of
+ * `gea::embedded::ui::Document::instance().createDocumentFragment()` would be a
+ * second authority over a question the package answers, free to drift from it.
+ * A package that stops shipping the row leaves this `null`, and every fragment
+ * is then refused by name at emission rather than rendered through a call the
+ * host no longer has.
+ */
+export declare const geaElementFragment: () => string | null;
+/**
+ * The intrinsic tags gea builds as a TEXT NODE when they hold one text run.
+ *
+ * Read from the package rather than restated here, for the same reason every
+ * other host spelling is: `isTextNodeTag` in its `cpp-template-renderer.ts` is
+ * the list v1 has always used, and a second copy in this compiler is a second
+ * authority that can drift from it.
+ *
+ * Lowercased and de-duplicated on the way through, because the tag this
+ * compiler compares against is the one the SOURCE wrote and JSX intrinsics are
+ * lowercase by convention rather than by rule -- the same normalization the
+ * engine's own `Document::createElement` does before it dispatches.
+ */
+export declare const geaElementTextLeafTags: () => readonly string[];
+export {};