@geastack/compiler 1.0.15

package/dist/plugins/gea/plugin.js

@@ -0,0 +1,307 @@
+import { geaAfterRenderMemberName, geaRenderBridgeMemberName, geaRenderMemberName } from './contract.js';
+import { createGeaComponentClassProducer } from './component-classes.js';
+import { geaHostConstructors } from './constructors.js';
+import { geaElementFragment, geaElementTextLeafTags, geaHostConstants, geaHostFunctions, geaHostNamespaceMethods, geaHostNamespaceProperties, geaHostNamespacePropertySetters, geaHostNamespaceRoots, geaHostNamespaceRootTypes, geaHostPreambles, geaNativeProtocols, geaHostSingletons, geaEmbeddedIncludeGuard, geaProtocolCarriers } from './host.js';
+import { geaHostMemberVoidResults, geaHostMembers } from './members.js';
+import { lowerGeaElement } from './lower.js';
+import { createGeaSlotHook } from './slots.js';
+import { lowerGeaElementRef } from './element-ref.js';
+import { createGeaElementProducer } from './producer.js';
+import { geaCppPrelude, microtasksNamespace } from './prelude.js';
+import { lowerGeaRenderBridge } from './render-bridge.js';
+import { geaComponentInlineTransform } from './component-inline.js';
+import { geaReactiveSlotTransform } from './reactive-slots.js';
+/**
+ * gea, as a plugin.
+ *
+ * Everything this library adds to TypeScript lives behind this one object: what
+ * an element whose tag names a value means, which member of a constructed
+ * component produces its tree, and the runtime rows that make those claims
+ * checkable. Nothing in `src/` outside this directory knows any of it.
+ *
+ * The facts map is the whole of the state, and it is per-compilation by
+ * construction: `instantiate` creates it, the producer fills it while
+ * normalizing one program, and the lowering reads it while lowering that same
+ * program. A registry of long-lived instances would let a fact derived from one
+ * program be read back while compiling another -- a defect that reproduces only
+ * in whatever order the programs happened to be compiled in.
+ *
+ * `componentClasses` is the same shape of state for a different question:
+ * which class *declarations*, not which JSX elements, are gea's own. Both are
+ * filled while normalizing and read only while lowering, for the identical
+ * reason -- see `component-classes.ts` and `render-bridge.ts`.
+ */
+export const geaPlugin = {
+    name: 'gea',
+    instantiate: (options) => {
+        const facts = new Map();
+        const componentClasses = new Set();
+        const reactiveFields = new Map();
+        return {
+            producers: (context) => [
+                createGeaElementProducer(context, facts),
+                createGeaComponentClassProducer(context, componentClasses, reactiveFields)
+            ],
+            // Two rewrites, in this order, and the order is the point.
+            //
+            // A component invocation whose props only ever write PROPERTIES becomes
+            // the element it builds (`component-inline.ts`), so what follows sees an
+            // intrinsic element and binds each attribute at its own granularity
+            // rather than making the whole subtree re-runnable. An invocation it
+            // cannot prove that of is left exactly as written, and the second rewrite
+            // claims it whole as before.
+            //
+            // Then a JSX slot whose value is COMPUTED gets an immediately-invoked
+            // arrow around it, before the checker, so the expression exists as a
+            // thunk this compiler can re-run. See `reactive-slots.ts`.
+            transformSource: (input) => {
+                const inlined = geaComponentInlineTransform(input);
+                const source = inlined === null ? input : { fileName: input.fileName, text: inlined };
+                return geaReactiveSlotTransform(source) ?? inlined;
+            },
+            lower: (ctx, block, operation) => lowerGeaElement(ctx, block, operation, facts) || lowerGeaRenderBridge(ctx, block, operation, componentClasses),
+            // `ref` is the one attribute of an intrinsic element whose meaning runs
+            // the other way -- it names where the node goes. See `element-ref.ts`.
+            lowerElementProp: lowerGeaElementRef,
+            slotOf: createGeaSlotHook(facts),
+            capabilities: {
+                // `element:value` is this plugin's recipe, and it is claimed here
+                // because this plugin is what implements it: the lowering above turns
+                // such an element into a record allocation plus a call, or into a
+                // construction plus a call of the render member. Both are built from
+                // primitives the backend already claims -- nothing new is emitted, so
+                // nothing new is asserted about the backend.
+                // `element:fragment` joins it whenever the package still ships the
+                // document's own fragment row -- see `geaElementFragment`. Claimed
+                // from the same statement that renders it, so a package that drops
+                // the row drops the claim in the same step.
+                runtimeHelpers: new Set(geaElementFragment() === null ? ['element:value'] : ['element:value', 'element:fragment']),
+                propertyRecipes: new Set(),
+                // The host object model gea installs -- the document, the element tree,
+                // JSX. None of it is TypeScript, so none of it is the backend's to
+                // know; `host.ts` states each protocol together with the spelling that
+                // renders it.
+                nativeProtocols: geaNativeProtocols,
+                // The host types themselves, from the package that implements them,
+                // plus the one carrier that is derived rather than stated:
+                // `jsx-element@1` has no TypeScript declaration behind it (JSX is a
+                // language form whose meaning the host decides, not a type a host
+                // declares), so its row is read off the package's own `Element`
+                // spelling -- see `geaProtocolCarriers`.
+                nativeTypes: geaProtocolCarriers(),
+                // gea's own host types are, like Apple's, ambient declarations with
+                // no OTHER, structurally-unrelated ambient name standing in for them
+                // -- see `plugins/model.ts`'s `ambientTypeRealizations` and
+                // `webgl/plugin.ts` for the host this closes a gap for.
+                ambientTypeRealizations: new Map(),
+                hostMembers: geaHostMembers(),
+                hostMemberVoidResults: geaHostMemberVoidResults(),
+                // gea's document/element tree is reached, never constructed -- a
+                // program gets its nodes from the runtime rather than by `new`-ing one.
+                // But a handful of gea's OTHER host classes really are built with
+                // `new` (`WebSocket`, `RTCPeerConnection`, `MediaStream`,
+                // `MediaRecorder`, `AudioContext`, `Audio`), each backed by a real
+                // `gea::host` C++ class -- see `geaHostConstructors` (constructors.ts)
+                // for the package data this reads and why the tree/class split is not
+                // a contradiction.
+                hostConstructors: geaHostConstructors(),
+                // The host's free functions and the globals that are paths rather than
+                // values, from the same package statement as the types above.
+                // `requestAnimationFrame` is a function the engine exports;
+                // `deviceInfo`, `Display` and `navigator` are namespaces. Neither is
+                // an object, and reading either as one is what produced eight
+                // `extern` declarations nothing in the engine defines.
+                hostFunctions: geaHostFunctions(),
+                // This host declares each of its free functions once, so there is no
+                // name two of its declarations disagree about and nothing to key by
+                // file -- see `PluginCapabilities.hostFunctionsByDeclaration`.
+                hostFunctionsByDeclaration: new Map(),
+                // The one global this host holds an instance of and reaches by name;
+                // derived from the package's own receiverless document table.
+                hostSingletons: geaHostSingletons(),
+                // Same one-declaration-file reasoning as `hostFunctionsByDeclaration`
+                // above: this host's ambient globals are declared once, in one place,
+                // so there is no second file for a singleton name to disagree with.
+                hostSingletonsByDeclaration: new Map(),
+                // gea's engine is the browser's stand-in, not a subset of it: the names
+                // it does not implement are simply not declared for a gea program, so
+                // there is no ambient contract here to contradict.
+                absentGlobals: new Set(),
+                hostNamespaces: {
+                    roots: geaHostNamespaceRoots(),
+                    typeofs: new Map(),
+                    methods: geaHostNamespaceMethods(),
+                    properties: geaHostNamespaceProperties(),
+                    propertySetters: geaHostNamespacePropertySetters()
+                },
+                // Same reasoning again: one declaration file, so no namespace root
+                // name this host claims can disagree with itself.
+                hostNamespaceRootsByDeclaration: new Map(),
+                // The type behind each of those roots, from the package's own
+                // `hostGlobalObjectTypes` table -- see
+                // `PluginCapabilities.hostNamespaceRootTypes`.
+                hostNamespaceRootTypes: geaHostNamespaceRootTypes(),
+                // What a unit must declare before it may name one of those spellings.
+                hostPreambles: geaHostPreambles(),
+                // gea's host types are one runtime type wearing thirteen declared
+                // names (`NodeHandle`), not a hierarchy, so there is no derivation to
+                // state and every handle is exactly as related to every other as the
+                // shared carrier already makes it.
+                nativeBases: new Map(),
+                // gea's carriers are declared by `gea_runtime.h`, which every emitted
+                // unit already includes, so this library adds no header of its own.
+                nativeIncludes: new Map(),
+                // The host's own constants: `audioContext` is a global the engine
+                // defines and the program only ever reads.
+                nativeConstants: geaHostConstants(),
+                // Same one-declaration-file reasoning as `hostFunctionsByDeclaration`:
+                // nothing here for a second file to disagree with.
+                hostConstantsByDeclaration: new Map(),
+                // What the gea engine requires back from a compiled program.
+                //
+                // `core/packages/core/gea_app_entry.cpp` declares both and defines
+                // neither: `Application::frame` calls `generated::drainMicrotasks()`
+                // once per frame and `Application::init` calls
+                // `gea_cpp_clear_microtasks()` when an app starts. The queue they act
+                // on belongs to the program, not the engine, which is why the engine
+                // asks rather than implements -- and why a unit that omits them
+                // compiles cleanly and then fails at `ld`.
+                //
+                // The queue is the REACTIVE one. Promises settle synchronously here
+                // (`gea::Promise` defers nothing), but the coalescing applies do defer:
+                // a list or component rebuild is scheduled once per turn and has to
+                // land after the callback that wrote and before layout reads the tree.
+                // `Application::frame` calls `drainMicrotasks()` at exactly that point,
+                // so that is where the queue drains -- see `detail::microtaskQueue` in
+                // `gea_runtime.h`, and the frame-late rows an earlier zero-delay timer
+                // produced. `gea_cpp_clear_microtasks()` drops the same queue when an
+                // app starts, so a resident switch cannot rebuild the outgoing app's
+                // list against the incoming app's tree.
+                // What `<>...</>` is on this host, from the package's own document
+                // table -- see `PluginCapabilities.elementFragment`.
+                elementFragment: geaElementFragment(),
+                // The tag list is the package's (`isTextNodeTag`); whether an element's
+                // contents are one text run is the compiler's -- see `elementTextTags`.
+                elementTextTags: geaElementTextLeafTags(),
+                // The members this host's own lowering calls without the program
+                // naming them, so `reachability.ts` never drops one: the render bridge
+                // rebuilds `instance.render(root, depth)` as a call to the class's own
+                // `template` (`render-bridge.ts`), and attaches the mounted tree by
+                // calling `onAfterRender` when the class declares it. `render` itself
+                // is spelled by every app that mounts a component, but a component
+                // whose `render` is reached only through the framework's own mount
+                // path is not, so it is stated rather than assumed.
+                reachedMemberKeys: new Set([geaRenderMemberName, geaRenderBridgeMemberName, geaAfterRenderMemberName]),
+                // Filled by the producer above while this program is normalized, and
+                // read by the target after it -- the same shared-by-reference state as
+                // `facts` and `componentClasses`, and per-compilation for the same
+                // reason. See `PluginCapabilities.reactiveClassFields`.
+                reactiveClassFields: reactiveFields,
+                // The engine's own reactive cell, named here rather than derived: it
+                // is gea's runtime type, so this package is the only thing that knows
+                // its name.
+                nativeReactiveCell: 'gea::embedded::ui::Signal',
+                // ...and the only thing that knows where it is DECLARED. This used to
+                // be empty, on the claim that `gea_runtime.h` already carries the cell.
+                // It does not: that header forward-declares `gea::embedded::ui::Signal`
+                // and says so at the declaration, because `ui/signal.h` is on the
+                // include path for an engine build only. A JSX program includes the
+                // engine for its own reasons and so never noticed; an ordinary program
+                // with a reactive field failed at the field declaration with "implicit
+                // instantiation of undefined template", which then cascaded into every
+                // conversion touching the class and read as an unrelated inheritance
+                // defect.
+                //
+                // The same guarded block the package states ahead of each of its 331
+                // host spellings, taken from `geaHostPreambles` rather than restated,
+                // so this compilation has one spelling of the engine include and a unit
+                // that carries both gets it once.
+                nativeReactiveCellPreamble: geaEmbeddedIncludeGuard(),
+                // gea's runtime reaches a unit as `gea_runtime.h`, which the support
+                // header states unconditionally for every build because every emitted
+                // unit is compiled against it -- it is the CLI's own line, not this
+                // plugin's contribution, so there is nothing to add here.
+                generatedSupportIncludes: [],
+                runtimeDefinitions: [
+                    // The namespace is the BUILD's to state, not this file's. A resident
+                    // build links several apps into one binary and gives each its own
+                    // `gea::framework::app::generated::gea_resident_<id>`, which the
+                    // generated entry shim forward-declares by exactly that name
+                    // (`targets/web/generate-resident-entry.mjs`); the pipeline passes it
+                    // as `gea.microtasks-namespace`, derived from the entry symbol.
+                    // Hardcoding the unsuffixed namespace defined a symbol no shim ever
+                    // declares AND defined it four times over -- one undefined reference
+                    // and one duplicate-symbol error from the same line.
+                    // Guarded on the same condition that decides whether the queue
+                    // EXISTS. `gea::jsx::detail`'s coalescing half lives inside
+                    // `#ifdef GEA_HOST_DECLARED` in `gea_runtime.h` -- it is reached only
+                    // through `reactiveListApply`/`reactiveNodeApply`, which name the
+                    // engine's `Signal` in their own signatures and so cannot be declared
+                    // in a unit that links no engine. A program that names no host
+                    // spelling emits no host preamble, hence no guard, hence no queue;
+                    // its body stays empty, which is also the right answer, since a unit
+                    // with no engine has no list to rebuild.
+                    {
+                        text: `namespace ${microtasksNamespace(options)} {\nvoid drainMicrotasks() {\n#ifdef GEA_HOST_DECLARED\n  ::gea::jsx::detail::drainMicrotasks();\n#endif\n}\n}`,
+                        requires: null
+                    },
+                    // Weak, and at global scope, for the reason
+                    // `core/packages/core/test/test_gea_resident_app_switch_main.cpp`
+                    // states beside its own declaration: every resident's unit defines
+                    // this, the engine calls it by the unsuffixed name, and the linker
+                    // has to collapse the definitions rather than reject them. v1 emits
+                    // it with the same attribute.
+                    {
+                        text: 'void __attribute__((weak)) gea_cpp_clear_microtasks() {\n#ifdef GEA_HOST_DECLARED\n  ::gea::jsx::detail::clearMicrotasks();\n#endif\n}',
+                        requires: null
+                    },
+                    // The engine's other pair of program-side entry points, declared the
+                    // same way and for the same reason: `core/packages/core/gea_app_entry.cpp`
+                    // wraps `Application::init` and `Application::frame` in a
+                    // `FrameCycleCollectionDeferral`, whose whole job is to keep the
+                    // collector off the stack while a host callback still owns transient
+                    // references. The queue is the PROGRAM's, so the engine asks and the
+                    // generated unit answers.
+                    //
+                    // `_end` collects rather than only decrementing: the deferral exists
+                    // to move the safepoint to where the host stack has unwound, and a
+                    // decrement alone leaves the drained candidates until the next
+                    // allocation happens to cross the threshold -- one frame of garbage
+                    // retained per frame. `bad_alloc` is swallowed because the collector
+                    // runs at scope exit of a host callback that has already returned;
+                    // propagating there unwinds through the engine's own frame, and the
+                    // candidates it could not trace are still queued for the next
+                    // safepoint.
+                    //
+                    // Weak, at global scope, exactly as `gea_cpp_clear_microtasks` above:
+                    // a resident build links several apps into one binary and the linker
+                    // has to collapse the definitions rather than reject them.
+                    {
+                        text: 'extern "C" void __attribute__((weak)) gea_cycle_collection_defer_begin() {\n  ++gea::detail::cycleState().deferDepth;\n}',
+                        requires: 'cycle-collectable-program'
+                    },
+                    {
+                        text: 'extern "C" void __attribute__((weak)) gea_cycle_collection_defer_end() {\n' +
+                            '  auto& gea_state = gea::detail::cycleState();\n' +
+                            '  if (gea_state.deferDepth == 0) {\n' +
+                            '    std::fprintf(stderr, "gea: cycle collection deferral underflow\\n");\n' +
+                            '    std::abort();\n' +
+                            '  }\n' +
+                            '  --gea_state.deferDepth;\n' +
+                            '  try {\n' +
+                            '    gea::collectCyclesIfNeeded();\n' +
+                            '  } catch (const std::bad_alloc&) {\n' +
+                            '    std::fprintf(stderr, "gea: cycle collection deferred after allocation failure\\n");\n' +
+                            '  }\n' +
+                            '}',
+                        requires: 'cycle-collectable-program'
+                    },
+                    // The stylesheet the build compiled for this program -- see
+                    // `prelude.ts`. Empty for a program the build passed no prelude for,
+                    // which is every program outside the gea pipeline.
+                    ...geaCppPrelude(options).map((text) => ({ text, requires: null }))
+                ]
+            }
+        };
+    }
+};

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

@@ -0,0 +1,78 @@
+import type { PluginOptions } from '../model.js';
+/**
+ * The C++ the gea build generated for this program, carried into the unit.
+ *
+ * A gea app's stylesheet is not data the compiler reads. The shipping pipeline
+ * (`build-gea-vite-geatsc.mjs`) compiles every `.css` the program imports into
+ * a static tape of engine calls and hands the compiler the path to it, because
+ * the engine's `StyleSheet` is the only thing that can interpret it. A unit
+ * that omits it links and runs and draws every element at its default size --
+ * which for gea's `<div class="ball"/>` is nothing at all. There is no
+ * diagnostic for that anywhere: the program is correct, the styles simply were
+ * never registered.
+ *
+ * Two forms, both the gea plugin's own and both matching what v1's
+ * `geatsc-plugin-gea` emits for the same options, because the same engine has
+ * to link against the result. The object form registers on static
+ * initialization and is what a single-app firmware or a wasm module uses; the
+ * named-function form exists for resident builds, where several apps share one
+ * binary and each must register its own styles when it starts rather than all
+ * of them at load. `gea.cpp-prelude-symbol` is what asks for the second.
+ *
+ * `inline` on the registration object is load-bearing and is v1's own comment:
+ * an anonymous-namespace object gets one copy per translation unit, so a
+ * split-TU build re-registers the whole tape once per module.
+ *
+ * The app's tape is not the whole sheet. gea's engine ships no user-agent
+ * defaults at all, so the tag-driven styles a browser would apply are the
+ * compiler's to state -- see `user-agent-styles.ts` for what they are and for
+ * the inline-layout defect their absence produced. They go in ahead of the
+ * app's own rules, in the same body, because both prelude forms have exactly
+ * one place a resident build will call, and they are emitted for every app the
+ * pipeline builds rather than only for the ones that imported a `.css`: nine
+ * of the shipped examples have inline tags and no stylesheet at all, and under
+ * the narrower gate every one of them lost its heading sizes.
+ */
+export declare const geaCppPrelude: (options: PluginOptions) => readonly string[];
+/**
+ * Whether the unit this compilation emits talks to AppKit rather than to gea's
+ * own element tree.
+ *
+ * `gea.ir` says "the gea pipeline asked for this build"; it does not say the
+ * result links gea's UI engine, and for one target it does not. An
+ * apple-native app's emitted unit includes `gea/apple/native_bridge.h` and
+ * nothing else -- `gea/embedded.h` and `ui/internal.h` are absent, because the
+ * views really are `NSView`s -- so C++ naming `gea::embedded::ui::StyleSheet`
+ * does not compile there ("no member named 'StyleSheet' in namespace
+ * 'gea::embedded::ui'", six times, on `notes-native`). There are also no `<p>`
+ * or `<h1>` nodes in such a program for a user-agent rule to match, so the
+ * sheet has nothing to say about it either way.
+ *
+ * Read off `apple.metadata`, which the apple target's pipeline passes for
+ * exactly the builds that load the apple-native plugin -- the same kind of
+ * fact, from the same pipeline, as `gea.ir` above.
+ *
+ * Exported so `cli-emit.ts` can thread this same pipeline fact into
+ * `generated_support.hpp`'s Apple-ownership line, rather than re-deriving it
+ * by searching the rendered C++ for the include text this fact already
+ * decided to write.
+ */
+export declare const isAppleNativeBuild: (options: PluginOptions) => boolean;
+/** Whether this is a bare C++ identifier, so a name the build passed can be emitted as one. */
+/**
+ * The namespace this program's `drainMicrotasks()` is defined in.
+ *
+ * `core/packages/core/gea_app_entry.cpp` calls `generated::drainMicrotasks()`,
+ * and a resident build gives each app its own nested namespace so four units
+ * can each define one -- `gea::framework::app::generated::gea_resident_<id>`,
+ * which `targets/web/generate-resident-entry.mjs` forward-declares by name.
+ * The pipeline derives it from the entry symbol and states it here
+ * (`build-gea-vite-geatsc.mjs`, `microtasksNamespaceForEntry`), so this reads
+ * it rather than restating it: the package that owns the contract is the
+ * authority, and a namespace invented on this side is a symbol nothing
+ * declares.
+ *
+ * The fallback is the plain namespace a single-app build uses, which is what
+ * the pipeline itself passes when the entry symbol is not a resident's.
+ */
+export declare const microtasksNamespace: (options: PluginOptions) => string;

package/dist/plugins/gea/prelude.js

@@ -0,0 +1,153 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { geaUserAgentStyleSheet } from './user-agent-styles.js';
+/**
+ * The C++ the gea build generated for this program, carried into the unit.
+ *
+ * A gea app's stylesheet is not data the compiler reads. The shipping pipeline
+ * (`build-gea-vite-geatsc.mjs`) compiles every `.css` the program imports into
+ * a static tape of engine calls and hands the compiler the path to it, because
+ * the engine's `StyleSheet` is the only thing that can interpret it. A unit
+ * that omits it links and runs and draws every element at its default size --
+ * which for gea's `<div class="ball"/>` is nothing at all. There is no
+ * diagnostic for that anywhere: the program is correct, the styles simply were
+ * never registered.
+ *
+ * Two forms, both the gea plugin's own and both matching what v1's
+ * `geatsc-plugin-gea` emits for the same options, because the same engine has
+ * to link against the result. The object form registers on static
+ * initialization and is what a single-app firmware or a wasm module uses; the
+ * named-function form exists for resident builds, where several apps share one
+ * binary and each must register its own styles when it starts rather than all
+ * of them at load. `gea.cpp-prelude-symbol` is what asks for the second.
+ *
+ * `inline` on the registration object is load-bearing and is v1's own comment:
+ * an anonymous-namespace object gets one copy per translation unit, so a
+ * split-TU build re-registers the whole tape once per module.
+ *
+ * The app's tape is not the whole sheet. gea's engine ships no user-agent
+ * defaults at all, so the tag-driven styles a browser would apply are the
+ * compiler's to state -- see `user-agent-styles.ts` for what they are and for
+ * the inline-layout defect their absence produced. They go in ahead of the
+ * app's own rules, in the same body, because both prelude forms have exactly
+ * one place a resident build will call, and they are emitted for every app the
+ * pipeline builds rather than only for the ones that imported a `.css`: nine
+ * of the shipped examples have inline tags and no stylesheet at all, and under
+ * the narrower gate every one of them lost its heading sizes.
+ */
+export const geaCppPrelude = (options) => {
+    const file = options.get('gea.cpp-prelude');
+    const tapePath = file === undefined || file.length === 0 ? null : resolve(file);
+    // Two separate questions, and they were one gate until an app with no
+    // stylesheet turned up rendering its headings at body size. The tape is this
+    // program's own CSS, and only a program that imported some has one. The
+    // user-agent sheet belongs to every program the gea build compiles -- a
+    // `<h1>` is still a heading in an app that ships no `.css` -- so it is gated
+    // on `gea.ir`, which the pipeline passes for every app it builds and which
+    // nothing outside the pipeline passes. That second gate is load-bearing: a
+    // program compiled outside it (the corpus harness calls `compile()` with no
+    // plugin options at all) would otherwise be handed C++ naming
+    // `gea::embedded::ui::StyleSheet` in a unit that never declared it.
+    if (tapePath === null && !isPipelineBuild(options))
+        return [];
+    const symbol = options.get('gea.cpp-prelude-symbol');
+    const named = symbol !== undefined && isPlainIdentifier(symbol);
+    // A path the build named but never wrote is not an error here: the pipeline
+    // passes this option whenever the app COULD have styles, and an app with
+    // none leaves the file absent. What it must not do is fail closed on a
+    // program that simply has no CSS.
+    const tape = tapePath !== null && existsSync(tapePath) ? readFileSync(tapePath, 'utf8').trim() : '';
+    // The user-agent sheet goes FIRST: a program with no CSS of its own still
+    // has `<p>`s and `<h1>`s, and the cascade breaks equal-specificity ties by
+    // source order, so anything the app states about the same tag has to be
+    // registered after this to win.
+    const body = tape.length === 0 ? geaUserAgentStyleSheet : `${geaUserAgentStyleSheet}\n${tape}`;
+    const provenance = `// @geastack/compiler gea C++ prelude\n// prelude=${tapePath ?? '<none: user-agent defaults only>'}`;
+    if (named)
+        return [`${provenance}\nvoid ${symbol}() {\n${indent(body, '  ')}\n}`];
+    return [
+        `${provenance}\nstruct GeaPluginCppPreludeRegistration {\n  GeaPluginCppPreludeRegistration() {\n${indent(body, '    ')}\n  }\n};\ninline GeaPluginCppPreludeRegistration gea_plugin_cpp_prelude_registration;`
+    ];
+};
+/**
+ * Whether the gea build pipeline is what asked for this compilation.
+ *
+ * `build-gea-vite-geatsc.mjs` passes `gea.ir` for every app it compiles, ahead
+ * of knowing whether that app has any CSS, and it is the one option that says
+ * "this unit is a gea app and links the engine". The user-agent sheet needs
+ * that to be true before it may name `gea::embedded::ui`, and a program
+ * compiled through the plain API states nothing of the kind.
+ */
+const isPipelineBuild = (options) => {
+    const ir = options.get('gea.ir');
+    return ir !== undefined && ir.length > 0 && !isAppleNativeBuild(options);
+};
+/**
+ * Whether the unit this compilation emits talks to AppKit rather than to gea's
+ * own element tree.
+ *
+ * `gea.ir` says "the gea pipeline asked for this build"; it does not say the
+ * result links gea's UI engine, and for one target it does not. An
+ * apple-native app's emitted unit includes `gea/apple/native_bridge.h` and
+ * nothing else -- `gea/embedded.h` and `ui/internal.h` are absent, because the
+ * views really are `NSView`s -- so C++ naming `gea::embedded::ui::StyleSheet`
+ * does not compile there ("no member named 'StyleSheet' in namespace
+ * 'gea::embedded::ui'", six times, on `notes-native`). There are also no `<p>`
+ * or `<h1>` nodes in such a program for a user-agent rule to match, so the
+ * sheet has nothing to say about it either way.
+ *
+ * Read off `apple.metadata`, which the apple target's pipeline passes for
+ * exactly the builds that load the apple-native plugin -- the same kind of
+ * fact, from the same pipeline, as `gea.ir` above.
+ *
+ * Exported so `cli-emit.ts` can thread this same pipeline fact into
+ * `generated_support.hpp`'s Apple-ownership line, rather than re-deriving it
+ * by searching the rendered C++ for the include text this fact already
+ * decided to write.
+ */
+export const isAppleNativeBuild = (options) => {
+    const metadata = options.get('apple.metadata');
+    return metadata !== undefined && metadata.length > 0;
+};
+/** Whether this is a bare C++ identifier, so a name the build passed can be emitted as one. */
+/**
+ * The namespace this program's `drainMicrotasks()` is defined in.
+ *
+ * `core/packages/core/gea_app_entry.cpp` calls `generated::drainMicrotasks()`,
+ * and a resident build gives each app its own nested namespace so four units
+ * can each define one -- `gea::framework::app::generated::gea_resident_<id>`,
+ * which `targets/web/generate-resident-entry.mjs` forward-declares by name.
+ * The pipeline derives it from the entry symbol and states it here
+ * (`build-gea-vite-geatsc.mjs`, `microtasksNamespaceForEntry`), so this reads
+ * it rather than restating it: the package that owns the contract is the
+ * authority, and a namespace invented on this side is a symbol nothing
+ * declares.
+ *
+ * The fallback is the plain namespace a single-app build uses, which is what
+ * the pipeline itself passes when the entry symbol is not a resident's.
+ */
+export const microtasksNamespace = (options) => {
+    const stated = options.get('gea.microtasks-namespace');
+    return stated !== undefined && isNamespacePath(stated) ? stated : 'gea::framework::app::generated';
+};
+/** A `::`-separated path of plain identifiers, and nothing else -- this text is spliced into C++. */
+const isNamespacePath = (value) => {
+    const parts = value.split('::');
+    return parts.length > 0 && parts.every((part) => isPlainIdentifier(part));
+};
+const isPlainIdentifier = (value) => {
+    if (value.length === 0)
+        return false;
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        const letter = (code >= 65 && code <= 90) || (code >= 97 && code <= 122) || code === 95;
+        const digit = code >= 48 && code <= 57;
+        if (!letter && !(digit && index > 0))
+            return false;
+    }
+    return true;
+};
+const indent = (source, prefix) => source
+    .split('\n')
+    .map((line) => (line.length === 0 ? line : `${prefix}${line}`))
+    .join('\n');

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

@@ -0,0 +1,5 @@
+import type { OperationId } from '../../identity/ids.js';
+import type { FamilyProducer } from '../../semantics/normalize/contribution.js';
+import type { ProducerContext } from '../../semantics/normalize/producer-context.js';
+import { type GeaElementFacts } from './contract.js';
+export declare const createGeaElementProducer: (context: ProducerContext, facts: Map<OperationId, GeaElementFacts>) => FamilyProducer;

package/dist/plugins/gea/producer.js

@@ -0,0 +1,52 @@
+import ts from 'typescript';
+import { createElementProducer } from '../../semantics/normalize/producers/jsx.js';
+import { elementFactsOf } from './contract.js';
+/**
+ * gea's element producer.
+ *
+ * It publishes exactly what the core's does -- the same operations, the same
+ * identities, the same operand pairing -- and additionally records, for every
+ * element whose tag names a value, what gea says that element means. The two
+ * halves are deliberately not merged: the operations belong to the graph, which
+ * every stage reads, while the meaning belongs to gea and is read only by gea's
+ * own lowering. Putting the second on the operation would put a library's
+ * vocabulary into a model that other libraries also publish into.
+ *
+ * Delegating rather than reimplementing is a choice about drift, not effort.
+ * An element's identity is minted from its node and its family, and a second
+ * producer that minted its own would have to stay in agreement with the first
+ * forever; there is nothing about the *language* half of an element that gea
+ * disagrees with, so it does not restate it.
+ */
+/** The tag of an element node, or `null` for a fragment, which names none. */
+const tagNameOf = (node) => {
+    if (ts.isJsxSelfClosingElement(node))
+        return node.tagName;
+    if (ts.isJsxElement(node))
+        return node.openingElement.tagName;
+    if (ts.isJsxOpeningElement(node))
+        return node.tagName;
+    return null;
+};
+export const createGeaElementProducer = (context, facts) => {
+    const core = createElementProducer(context);
+    return {
+        family: core.family,
+        contribute: (candidate) => {
+            const contribution = core.contribute(candidate);
+            if (contribution.kind !== 'operations')
+                return contribution;
+            const tagName = tagNameOf(candidate.node);
+            if (!tagName)
+                return contribution;
+            for (const operation of contribution.operations) {
+                if (operation.family !== 'element' || operation.form !== 'value')
+                    continue;
+                const resolved = elementFactsOf(context.checker, tagName);
+                if (resolved)
+                    facts.set(operation.id, resolved);
+            }
+            return contribution;
+        }
+    };
+};

package/dist/plugins/gea/reactive-slots.d.ts

@@ -0,0 +1,49 @@
+import ts from 'typescript';
+import type { PluginSourceFile } from '../model.js';
+/**
+ * Whether this tag names a VALUE rather than an intrinsic name.
+ *
+ * JSX's own rule, and the same one `producers/jsx.ts`'s `intrinsicTagOf` reads:
+ * a lowercase-initial plain identifier is an intrinsic name, anything else --
+ * `ClockHand`, `ui.Row` -- resolves as a value. A namespaced name is never a
+ * component.
+ */
+export declare const namesAComponent: (tag: ts.JsxTagNameExpression) => boolean;
+export declare const openingOf: (element: ts.JsxElement | ts.JsxSelfClosingElement) => ts.JsxOpeningLikeElement;
+/**
+ * A COMPONENT element in a child position, whose props are computed from
+ * something read out of an object.
+ *
+ * This is the one JSX position whose reactivity nothing else can reach.
+ * `plugins/gea/lower.ts` lowers `<ClockHand angle={clock.second}/>` to what the
+ * checker checked -- a props record built from the attributes, and a call --
+ * so the reactive field is read ONCE, into a plain field of that record, and
+ * the callee's body then sees an ordinary parameter. Every reactive binding
+ * this backend has is attached at an INTRINSIC element's own prop or child
+ * (`targets/cpp/emit-jsx.ts`), and there is no intrinsic element here: the
+ * emitter cannot bind a member pointer through a call it cannot see inside.
+ *
+ * So the re-runnable unit is the whole invocation -- props record and call
+ * together -- which is exactly what wrapping the element in an IIFE makes it.
+ * Re-running the call alone would not do: it would hand the callee the SAME
+ * record, still holding the value the first render read.
+ *
+ * Claimed only in a child position. A component element that is a function's
+ * return value (`return <AnalogClockView/>`) is not a slot of anything -- there
+ * is no parent node to re-attach a rebuilt subtree to -- and the rewrite would
+ * only add a call.
+ *
+ * And only under an INTRINSIC parent. The re-attach point this rewrite is for
+ * is an `element-child` operation on a real host node -- the only place
+ * `targets/cpp/emit-jsx.ts` can write `reactiveNodeApply` -- and only an
+ * intrinsic element lowers to one. A component nested directly inside another
+ * COMPONENT element (`<UILabel/>` under `<UIView>`, as every apple-native app
+ * writes its tree) is not a child slot of a node at all: it is an attribute of
+ * the props record the outer component's own invocation builds, attached by
+ * that call rather than by this compiler. Wrapping it offers a re-run nothing
+ * can attach -- and measurably costs: it moves the element out of the position
+ * whose type the checker had, so `producers/jsx.ts` sees `any` and blocks the
+ * census (four `ios-*` apps lost their certificate on exactly this).
+ */
+export declare const isReactiveComponentChild: (node: ts.Node) => node is ts.JsxElement | ts.JsxSelfClosingElement;
+export declare const geaReactiveSlotTransform: ({ fileName, text }: PluginSourceFile) => string | null;