@geastack/compiler 1.0.15

package/dist/plugins/apple/jsx.js

@@ -0,0 +1,293 @@
+import ts from 'typescript';
+import { appleNativeTypes } from './host.js';
+import { appleHostMembers, appleMethodParameters } from './members.js';
+/**
+ * Apple's JSX, rewritten into the construction it always meant.
+ *
+ * ## Why this cannot be a producer
+ *
+ * Everything else this plugin does reads the checker's answer. This cannot,
+ * because for JSX over AppKit the checker has no answer to give:
+ *
+ * - Every JSX element is typed `JSX.Element`, never the tag's own class. That
+ *   is the language's rule, not a configuration: the element type comes from
+ *   the JSX namespace in scope. Measured against `jsx: "react-jsx"` with a
+ *   factory declared `<T extends new () => NSView>(type: T, props:
+ *   Partial<InstanceType<T>>): InstanceType<T>` -- the namespace's `Element`
+ *   still wins, so `<NSStackView/>` is not an `NSStackView` to anything
+ *   downstream.
+ * - JSX attribute checking requires the component to have a PROPS PARAMETER.
+ *   An AppKit class does not have one, so `spacing="not-a-number"` produces no
+ *   diagnostic whatsoever -- an entire class of author error passes silently.
+ *
+ * So a producer running after the checker would be handed `JSX.Element` and a
+ * bag of unchecked attributes, and would have to re-derive from syntax what the
+ * type system was supposed to establish. The element has to become ordinary
+ * TypeScript BEFORE the checker runs, which is what v1 does -- a Babel
+ * transform in `vite-plugin-apple-native`, whose output shape this reproduces
+ * exactly. After the rewrite the checker types `new NSStackView()` as an
+ * `NSStackView` and checks `stack.spacing = 8` against the real declared
+ * property, which is the entire point.
+ *
+ * ## What decides which tags are claimed
+ *
+ * `appleNativeTypes()`, and nothing else. v1's transform carries a hardcoded
+ * list of twenty-two tag names, which is a second copy of a fact the SDK
+ * package already states and which goes stale the first time the SDK grows a
+ * class. A tag this host does not own is left untouched, so a file mixing
+ * AppKit elements with another library's is rewritten only where it should be.
+ *
+ * Whether a child is added with `addArrangedSubview` or `addSubview` is decided
+ * the same way -- by asking whether the parent's carrier has an
+ * `addArrangedSubview` member -- rather than by a second hardcoded list of the
+ * three stack-shaped classes.
+ *
+ * ## Why text, and why splicing
+ *
+ * Text in, text out: what the checker parses is a program a person could have
+ * written, and every stage after it behaves as though the author wrote that.
+ * The rewrite splices only the ranges the elements occupy, innermost text taken
+ * from the original source, so every other byte of the file -- comments,
+ * formatting, the code around the element -- survives exactly. Reprinting the
+ * file through TypeScript's printer would have been less code and would have
+ * rewritten lines nothing asked to change.
+ */
+/** The name a JSX tag spells, when it is a plain identifier; `null` for a qualified or namespaced tag. */
+const tagNameOf = (element) => ts.isIdentifier(element.tagName) ? element.tagName.text : null;
+const claimedElement = (node, carriers) => {
+    if (ts.isJsxSelfClosingElement(node)) {
+        const tag = tagNameOf(node);
+        return tag !== null && carriers.has(tag) ? { node, opening: node, tag, children: [] } : null;
+    }
+    if (!ts.isJsxElement(node))
+        return null;
+    const tag = tagNameOf(node.openingElement);
+    return tag !== null && carriers.has(tag) ? { node, opening: node.openingElement, tag, children: node.children } : null;
+};
+/**
+ * The call that adds a child to this parent, as the parent's own type decides.
+ *
+ * A stack view arranges its children with Auto Layout and takes them through
+ * `addArrangedSubview`; every other view takes them through `addSubview`, and
+ * handing a stack view the second silently produces a view with an unarranged,
+ * unpositioned child. The member table is what knows which is which, so the
+ * question is asked of it rather than of a list of class names kept here.
+ */
+const childAdderOf = (carrier, members) => members.has(`${carrier}.addArrangedSubview`) ? 'addArrangedSubview' : 'addSubview';
+/** The source text of a node, exactly as the author wrote it. */
+const sourceTextOf = (node, file) => node.getText(file);
+/**
+ * One attribute's value as an expression.
+ *
+ * A valueless attribute is `true`, which is JSX's own rule for one. A string
+ * literal and an expression container are both taken verbatim -- the author's
+ * text is the value, and re-rendering it would be this file deciding how their
+ * expression should look.
+ */
+const attributeValueText = (attribute, file, tag) => {
+    const initializer = attribute.initializer;
+    if (initializer === undefined)
+        return 'true';
+    if (ts.isStringLiteral(initializer))
+        return sourceTextOf(initializer, file);
+    if (ts.isJsxExpression(initializer) && initializer.expression)
+        return sourceTextOf(initializer.expression, file);
+    throw new Error(`<${tag}> has an attribute with no value expression; an Apple native element sets properties, and a property needs a value`);
+};
+/** The object literal an attribute's value is, or `null` when it is any other expression. */
+const objectLiteralOf = (attribute) => {
+    const initializer = attribute.initializer;
+    if (initializer === undefined || !ts.isJsxExpression(initializer) || !initializer.expression)
+        return null;
+    return ts.isObjectLiteralExpression(initializer.expression) ? initializer.expression : null;
+};
+/**
+ * An object-literal attribute CONFIGURES the member it names; it does not
+ * replace it.
+ *
+ * `layer={{ cornerRadius: 6 }}` is the case that proves the rule, and the
+ * checker is what proves it: `layer` is declared read-only -- a view owns its
+ * layer and a program cannot hand it a different one -- so rewriting the
+ * attribute as `view.layer = { … }` produces "Cannot assign to 'layer' because
+ * it is a read-only property", correctly. What the author means is the six
+ * words the object spells out: set these properties on the layer this view
+ * already has. So each property becomes its own assignment through the member.
+ *
+ * Stated generally rather than for `layer` alone (v1 names that one property):
+ * nothing about the rule is specific to layers, and a list of member names kept
+ * here would be one more copy of the host's own model.
+ */
+const objectAttributeStatements = (view, member, literal, file, tag) => literal.properties.map((property) => {
+    if (!ts.isPropertyAssignment(property)) {
+        throw new Error(`<${tag}> configures "${member}" with an entry that is not a plain \`name: value\`; each one becomes an assignment, and only a named property has a name to assign through`);
+    }
+    if (!ts.isIdentifier(property.name) && !ts.isStringLiteral(property.name)) {
+        throw new Error(`<${tag}> configures "${member}" through a computed property name; the property a value lands on has to be known here, before the checker types it`);
+    }
+    return `${view}.${member}.${property.name.text} = ${sourceTextOf(property.initializer, file)};`;
+});
+/** The setter spelling of an attribute name: `title` becomes `setTitle`. */
+const setterNameOf = (attribute) => `set${attribute.slice(0, 1).toUpperCase()}${attribute.slice(1)}`;
+/**
+ * The value a parameter the attribute form cannot spell takes.
+ *
+ * `setTitle:forState:` has a control state and `setOn:animated:` has an
+ * animation flag; an attribute states one value and says nothing about either.
+ * What it means by saying nothing is the plain case -- the title in the normal
+ * state, set without animation -- and on this platform the plain case is the
+ * zero of the parameter's own declared type: control state `0` is `.normal`,
+ * `animated: false` is no animation.
+ *
+ * A parameter of any other kind has no such value. An object cannot be
+ * defaulted -- there is no empty `UIColor` that means "unspecified" -- and a
+ * primitive the SDK names something other than `number` or `boolean` is an
+ * enumeration whose zero this file has no standing to pick. Both are refused
+ * rather than guessed.
+ */
+const parameterZeroOf = (type) => {
+    if (type?.kind !== 'primitive')
+        return null;
+    if (type.name === 'number')
+        return '0';
+    return type.name === 'boolean' ? 'false' : null;
+};
+/**
+ * An attribute the class states only as a setter.
+ *
+ * `<UIButton title="Go"/>`: a button has no `title` property, because a
+ * button's title is per control state, so UIKit spells it
+ * `setTitle:forState:`. Assigning the attribute as a property would emit
+ * `button.title = "Go"`, which the checker rejects outright -- and did, on five
+ * iOS programs, the moment this transform started producing code the checker
+ * actually types.
+ *
+ * Which attributes these are is not a list kept here. v1's transform names
+ * three of them; this asks the host's own tables the question those three are
+ * the answer to -- the carrier states no member `title`, and does state a
+ * method `setTitle` -- so a class that grows a fourth is carried without an
+ * edit here, and one that turns a setter into a property stops being routed
+ * without one either.
+ *
+ * `null` when the attribute is an ordinary property, which is nearly all of
+ * them: the caller then assigns it as written.
+ */
+const setterStatement = (view, carrier, attribute, valueText, members, tag) => {
+    if (members.has(`${carrier}.${attribute}`))
+        return null;
+    const setter = setterNameOf(attribute);
+    if (!members.has(`${carrier}.${setter}`))
+        return null;
+    const parameters = appleMethodParameters(carrier, setter);
+    if (parameters === null)
+        return null;
+    const rest = parameters.slice(1).map((parameter) => {
+        const zero = parameterZeroOf(parameter.type);
+        if (zero === null) {
+            throw new Error(`<${tag}> sets "${attribute}" through ${setter}, which takes a further argument of a kind an attribute cannot leave unstated; ` +
+                `call ${setter} directly with every argument it needs`);
+        }
+        return zero;
+    });
+    return `${view}.${setter}(${[valueText, ...rest].join(', ')});`;
+};
+/**
+ * The whole element as one expression: build it, configure it, hand it back.
+ *
+ * An immediately-invoked arrow, because a JSX element is an EXPRESSION and the
+ * work it stands for is a sequence of statements. That is v1's shape too, and
+ * it is what lets an element appear wherever the author put one -- an
+ * initializer, an argument, a child of another element -- without this
+ * transform having to know where it landed.
+ */
+const elementExpressionText = (claimed, file, carriers, members, nextName) => {
+    const view = nextName();
+    const carrier = carriers.get(claimed.tag) ?? '';
+    const statements = [`const ${view} = new ${claimed.tag}();`];
+    for (const attribute of claimed.opening.attributes.properties) {
+        if (!ts.isJsxAttribute(attribute) || !ts.isIdentifier(attribute.name)) {
+            // A spread carries names known only at run time, and a property assigned
+            // by a name nothing states is exactly the unchecked write this transform
+            // exists to eliminate.
+            throw new Error(`<${claimed.tag}> spreads its attributes; an Apple native element states each property it sets, by name`);
+        }
+        const literal = objectLiteralOf(attribute);
+        if (literal) {
+            statements.push(...objectAttributeStatements(view, attribute.name.text, literal, file, claimed.tag));
+            continue;
+        }
+        const value = attributeValueText(attribute, file, claimed.tag);
+        const setter = setterStatement(view, carrier, attribute.name.text, value, members, claimed.tag);
+        statements.push(setter ?? `${view}.${attribute.name.text} = ${value};`);
+    }
+    const adder = childAdderOf(carrier, members);
+    for (const child of claimed.children) {
+        const nested = claimedElement(child, carriers);
+        if (nested) {
+            statements.push(`${view}.${adder}(${elementExpressionText(nested, file, carriers, members, nextName)});`);
+            continue;
+        }
+        if (ts.isJsxExpression(child)) {
+            if (child.expression)
+                statements.push(`${view}.${adder}(${sourceTextOf(child.expression, file)});`);
+            continue;
+        }
+        if (ts.isJsxText(child)) {
+            if (child.text.trim().length > 0) {
+                throw new Error(`<${claimed.tag}> has text between its tags; an AppKit view holds subviews, and text belongs to a field's own string property`);
+            }
+            continue;
+        }
+        throw new Error(`<${claimed.tag}> has a child this transform does not read; an Apple native element's children are elements or expressions`);
+    }
+    statements.push(`return ${view};`);
+    return `(() => { ${statements.join(' ')} })()`;
+};
+/**
+ * The outermost claimed elements in a file, in source order.
+ *
+ * Outermost only: a claimed element renders its own children itself, from the
+ * original AST, so descending into one would rewrite the same text twice.
+ */
+const claimedRootsOf = (file, carriers) => {
+    const roots = [];
+    const visit = (node) => {
+        const claimed = claimedElement(node, carriers);
+        if (claimed) {
+            roots.push(claimed);
+            return;
+        }
+        ts.forEachChild(node, visit);
+    };
+    ts.forEachChild(file, visit);
+    return roots;
+};
+export const appleJsxTransform = ({ fileName, text }) => {
+    // JSX is only JSX in a file whose extension says the parser should read it as
+    // such, and a file with no `<` cannot contain an element -- one substring test
+    // is what a file this plugin has nothing to do with costs.
+    if (!fileName.endsWith('.tsx') && !fileName.endsWith('.jsx'))
+        return null;
+    if (!text.includes('<'))
+        return null;
+    const carriers = appleNativeTypes();
+    if (carriers.size === 0)
+        return null;
+    const file = ts.createSourceFile(fileName, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+    const roots = claimedRootsOf(file, carriers);
+    if (roots.length === 0)
+        return null;
+    const members = appleHostMembers();
+    let counter = 0;
+    const nextName = () => `__geaAppleView${counter++}`;
+    // Spliced from the end so every earlier element's range is still the range it
+    // was measured at. Rewriting forwards would need every later position
+    // adjusted by the length each replacement changed, which is the same answer
+    // with an off-by-one to find.
+    let rewritten = text;
+    for (const claimed of [...roots].reverse()) {
+        const start = claimed.node.getStart(file);
+        rewritten =
+            rewritten.slice(0, start) + elementExpressionText(claimed, file, carriers, members, nextName) + rewritten.slice(claimed.node.end);
+    }
+    return rewritten;
+};

package/dist/plugins/apple/members.d.ts

@@ -0,0 +1,16 @@
+import type { HostMemberTable } from '../../targets/cpp/host/host-members.js';
+import { type AppleMethodParameter } from './host.js';
+export declare const appleHostMembers: () => HostMemberTable;
+/**
+ * The parameters a class declares for one of its methods.
+ *
+ * Walked up the chain the class extends, because a method is declared once, on
+ * the class that introduces it, while the member tables list every receiver
+ * that inherits it -- so "this carrier accepts `setTitle`" and "this class
+ * declares `setTitle`" are answered by two different rows, and only the second
+ * one carries the parameter list.
+ *
+ * `null` when nothing in the chain declares the method, which is a real answer
+ * and not an empty parameter list: a method with no parameters states `[]`.
+ */
+export declare const appleMethodParameters: (carrier: string, method: string) => readonly AppleMethodParameter[] | null;

package/dist/plugins/apple/members.js

@@ -0,0 +1,190 @@
+import { templateArity } from '../../targets/cpp/host/host-members.js';
+import { appleBridgeMetadata, appleMemberTables, appleNativeTypes } from './host.js';
+/**
+ * The carriers a binding applies to.
+ *
+ * A binding lists every spelling of every receiver it accepts -- the bare
+ * ObjC name (`NSView`), the pointer form (`NSView *`), the C++ wrapper
+ * (`gea::apple::AppKit::NSView`), and `gea_cpp_value`. Only the wrapper form is
+ * kept, because that is the carrier this compiler keys a host member by, and
+ * the bare and pointer forms are the same type under two other names.
+ *
+ * `gea_cpp_value` is dropped deliberately and permanently. It is v1's boxed
+ * receiver -- the dynamic fallback that lets a member resolve off a value whose
+ * type was erased -- and admitting it here would make every AppKit member
+ * reachable through the box this compiler exists not to produce.
+ */
+const carriersOf = (binding) => (binding.receiverTypes ?? []).filter((name) => name.startsWith('gea::apple::'));
+/**
+ * The other spelling convention this host states: a thunk, not a message send.
+ *
+ * Fifty of the Apple member rows carry `extern` instead of `emit` -- a C++ free
+ * function the generated bridge declares and defines, rather than an inline
+ * ObjC template. The calling convention is the package's own, stated in v1's
+ * `native-global-function-bindings.ts` where these tables are declared: "Reads
+ * and writes lower to configured extern names with the receiver as the first
+ * argument." The generated header says the same thing in C++ --
+ * `MTKView_get_currentRenderPassDescriptor(MTKView self)`,
+ * `MTKView_set_device(MTKView self, MTLDevice value)`.
+ *
+ * So the template is that call, and the only thing it needs beyond the row is
+ * how many arguments to pass. A getter takes none and a setter takes the value;
+ * a method takes what the class DECLARES, which the metadata one step upstream
+ * still knows (`appleMethodParameters`) and these tables no longer do. A method
+ * whose declaration cannot be found renders nothing rather than a call with a
+ * guessed arity: that would be a link error naming a symbol the program never
+ * wrote, in place of a refusal naming the member it could not spell.
+ */
+const externTemplate = (name, binding, carrier, slots) => {
+    const symbol = binding.extern;
+    if (symbol === undefined || symbol.length === 0)
+        return null;
+    if (slots === 'none')
+        return `${symbol}({receiver})`;
+    if (slots === 'value')
+        return `${symbol}({receiver}, {value})`;
+    const parameters = appleMethodParameters(carrier, name);
+    if (parameters === null)
+        return null;
+    const args = parameters.map((_, position) => `, {arg${position}}`).join('');
+    return `${symbol}({receiver}${args})`;
+};
+const addRows = (rows, table, slots, member) => {
+    for (const [name, bindings] of Object.entries(table ?? {})) {
+        for (const binding of bindings) {
+            for (const carrier of carriersOf(binding)) {
+                const emit = binding.emit !== undefined && binding.emit.length > 0 ? binding.emit : externTemplate(name, binding, carrier, slots);
+                if (emit === null || emit === undefined || emit.length === 0)
+                    continue;
+                const key = `${carrier}.${name}`;
+                const row = member(emit, rows.get(key));
+                if (row)
+                    rows.set(key, row);
+            }
+        }
+    }
+};
+/**
+ * Apple's host members, keyed the way this backend keys every host member:
+ * `<carrier>.<member>`.
+ *
+ * The package states them the other way round -- keyed by member name, each
+ * binding listing the receiver types it accepts -- because that is the shape
+ * its own emitter looks members up in. Transposing here is not restating the
+ * data: every template, every receiver list and every cast stays in the package
+ * that generates it, and this is the one place that says which of the two
+ * indexes this compiler reads.
+ *
+ * A getter and a setter for one member are two rows in the package and one row
+ * here, merged by key, because a read and a write of `view.frame` are two
+ * directions of a single property and `HostMember` states them as such. The
+ * first binding to claim a key wins; a later one with different text for the
+ * same carrier and member would be the package disagreeing with itself, and
+ * silently overwriting would hide that.
+ */
+/**
+ * A class object's own members, added under the carrier its instances use.
+ *
+ * `NSColor.clearColor` is a message to the class and `color.blendedColorWith`
+ * is a message to an object, but the declaration file names the class and the
+ * instance type with one identifier, so `nativeTypes` maps that one name to one
+ * C++ wrapper and both member sets are reached under one key.
+ *
+ * That is safe only while no class states a static and an instance member of
+ * the same name -- measured: zero collisions across all 58 Apple statics. It is
+ * not safe by construction, and the failure would be silent: the wrong template
+ * renders and clang accepts it, because both spell a valid message send. So the
+ * invariant is enforced rather than assumed. A collision means the packages now
+ * state something this key space cannot hold, and the fix is upstream of here.
+ */
+const addNamespaceRows = (rows, shims) => {
+    const carriers = appleNativeTypes();
+    for (const [className, members] of Object.entries(shims.nativeNamespaceMethods ?? {})) {
+        const carrier = carriers.get(className);
+        // A class the type table does not carry has no key to file its statics
+        // under, and inventing one would claim a member of a protocol nothing
+        // binds. Skipping is the honest answer: no claim, so no drift.
+        if (carrier === undefined)
+            continue;
+        for (const [name, member] of Object.entries(members)) {
+            const emit = member.emit;
+            if (emit === undefined || emit.length === 0)
+                continue;
+            const key = `${carrier}.${name}`;
+            if (rows.has(key)) {
+                throw new Error(`apple host members: "${key}" is stated both as a member of ${className} instances and as a member of the ` +
+                    `${className} class object; one key cannot render both, and choosing either silently renders the wrong message send`);
+            }
+            rows.set(key, { kind: 'method', emit, arity: templateArity(emit) });
+        }
+    }
+};
+export const appleHostMembers = () => {
+    const shims = appleMemberTables();
+    if (!shims)
+        return new Map();
+    const rows = new Map();
+    addRows(rows, shims.nativeMemberMethods, 'declared', (emit, existing) => existing ? null : { kind: 'method', emit, arity: templateArity(emit) });
+    addRows(rows, shims.nativeMemberPropertyGetters, 'none', (emit, existing) => existing?.kind === 'property' ? (existing.emit === null ? { ...existing, emit } : null) : { kind: 'property', emit, store: null });
+    addRows(rows, shims.nativeMemberPropertySetters, 'value', (emit, existing) => existing?.kind === 'property'
+        ? existing.store === null
+            ? { ...existing, store: emit }
+            : null
+        : existing
+            ? null
+            : { kind: 'property', emit: null, store: emit });
+    // Last, so the collision guard above sees every instance member already
+    // filed: a static added first would be the thing an instance member
+    // overwrote, and the overwrite is exactly what must not happen quietly.
+    addNamespaceRows(rows, shims);
+    return rows;
+};
+/**
+ * The metadata classes, indexed by the C++ wrapper each one's values carry.
+ *
+ * The metadata keys a class by `Framework.Class`, which is the spelling
+ * `extends` uses and so the one the chain walk below follows; the carrier is
+ * what every other table here is keyed by. Both indexes come from the same
+ * rows, so this is the metadata's own `wrapper` field read backwards rather
+ * than a second naming rule that could disagree with it.
+ */
+let byCarrier = null;
+const carrierIndex = () => {
+    if (byCarrier)
+        return byCarrier;
+    const index = new Map();
+    for (const [key, entry] of Object.entries(appleBridgeMetadata().classes ?? {})) {
+        if (typeof entry.wrapper === 'string' && entry.wrapper.length > 0)
+            index.set(entry.wrapper, key);
+    }
+    byCarrier = index;
+    return index;
+};
+/**
+ * The parameters a class declares for one of its methods.
+ *
+ * Walked up the chain the class extends, because a method is declared once, on
+ * the class that introduces it, while the member tables list every receiver
+ * that inherits it -- so "this carrier accepts `setTitle`" and "this class
+ * declares `setTitle`" are answered by two different rows, and only the second
+ * one carries the parameter list.
+ *
+ * `null` when nothing in the chain declares the method, which is a real answer
+ * and not an empty parameter list: a method with no parameters states `[]`.
+ */
+export const appleMethodParameters = (carrier, method) => {
+    const classes = appleBridgeMetadata().classes ?? {};
+    let key = carrierIndex().get(carrier);
+    const seen = new Set();
+    while (key !== undefined && !seen.has(key)) {
+        seen.add(key);
+        const entry = classes[key];
+        if (entry === undefined)
+            return null;
+        const declared = entry.methods?.[method];
+        if (declared !== undefined)
+            return declared.parameters ?? [];
+        key = entry.extends;
+    }
+    return null;
+};

package/dist/plugins/apple/plugin.d.ts

@@ -0,0 +1,2 @@
+import type { CompilerPlugin } from '../model.js';
+export declare const applePlugin: CompilerPlugin;

package/dist/plugins/apple/plugin.js

@@ -0,0 +1,156 @@
+import { noHostNamespaces } from '../../targets/cpp/host/host-members.js';
+import { appleNativeTypes, writeAppleBridgeArtifacts } from './host.js';
+import { appleHostConstructors, appleHostFunctions, appleHostFunctionsByDeclaration, appleNativeBases, appleNativeBridgeHeader, appleNativeConstants, appleNativeIncludes } from './constructors.js';
+import { appleHostMembers } from './members.js';
+import { appleJsxTransform } from './jsx.js';
+/**
+ * Apple's native frameworks, as a plugin.
+ *
+ * Data only, for now, and deliberately so. `AppKit`, `Foundation` and their
+ * siblings are a *host's* description of itself: nothing about `NSView` or
+ * `NSTextField` is TypeScript, so a generic TypeScript-to-C++ compiler that
+ * knew how to render one would be asserting something about the program's
+ * environment that nothing in the program says. What it needs to be told is
+ * which declared type names that host owns and what its runtime carries their
+ * values in -- and that is exactly `nativeTypes`, which the Apple packages
+ * already generate for v1's build.
+ *
+ * No producer and no lowering: unlike gea, this host adds no meaning to a
+ * language form. An AppKit program is ordinary TypeScript calling methods on
+ * host objects, and the core compiles it as such the moment it knows those
+ * objects are host objects.
+ *
+ * The claim and the spelling travel together, as they must: `nativeTypes` is
+ * what makes a protocol claimable and `hostMembers` is what renders a member of
+ * it, and a plugin that stated one without the other would certify a program at
+ * preflight that emission then refuses by name.
+ */
+/**
+ * The `writeArtifacts` half of this plugin, present only when the build stated
+ * where its Apple metadata is.
+ *
+ * Spread into the instance rather than defined on it so a non-Apple build has
+ * no such property at all, which is the same thing `PluginInstance` says an
+ * absent hook means -- rather than a function that is installed and then
+ * decides at write time to do nothing, which is a second place for the
+ * condition to be stated and to drift from the first.
+ */
+const appleMetadataPath = (options) => {
+    const path = options.get('apple.metadata');
+    return path === undefined || path.length === 0 ? null : path;
+};
+const appleBridgeArtifacts = (options) => {
+    const metadataPath = appleMetadataPath(options);
+    if (metadataPath === null)
+        return {};
+    return { writeArtifacts: (outDir) => writeAppleBridgeArtifacts(metadataPath, outDir) };
+};
+export const applePlugin = {
+    name: 'apple-native',
+    instantiate: (options) => ({
+        producers: () => [],
+        lower: () => false,
+        // The bridge the emitted unit includes and the target links -- see
+        // `writeAppleBridgeArtifacts`. Installed only for a build that stated
+        // `apple.metadata`, which is exactly the build whose unit includes it:
+        // this plugin is installed unconditionally (its tables are data, and a
+        // program that names no Apple type reads none of them), so writing a
+        // bridge on the strength of installation alone would drop an AppKit header
+        // into every web and embedded app's output directory.
+        ...appleBridgeArtifacts(options),
+        // The one thing this host cannot state as data: JSX over its classes has to
+        // become construction before the checker runs, because the checker cannot
+        // type an element as its tag. See `jsx.ts` for what was measured.
+        transformSource: appleJsxTransform,
+        capabilities: {
+            runtimeHelpers: new Set(),
+            propertyRecipes: new Set(),
+            // Every protocol this plugin claims is derived from the carriers in
+            // `nativeTypes` (`compiler.ts` unions `${carrier}@1` in), so there is
+            // nothing to state twice here. A name absent from that table is not
+            // host-owned, and no protocol is claimed for it.
+            nativeProtocols: new Set(),
+            nativeTypes: appleNativeTypes(),
+            declarationModules: new Set([
+                process.env.GEATSC2_APPLE_SDK ?? '@geastack/apple',
+                `${process.env.GEATSC2_APPLE_SDK ?? '@geastack/apple'}/*`
+            ]),
+            // Apple's classes are ambient host declarations to begin with -- there
+            // is no OTHER, wrongly-stated ambient name for one of them to replace,
+            // which is the gap `ambientTypeRealizations` closes. See its own
+            // doc comment (`plugins/model.ts`) and `webgl/plugin.ts` for the host
+            // that actually needs one.
+            ambientTypeRealizations: new Map(),
+            hostMembers: appleHostMembers(),
+            // `AppleMemberBinding` (host.ts) states no `returnType` at all -- unlike
+            // gea's `GeaMemberBinding`, this plugin's member-method table carries no
+            // note of a real C++ return diverging from the checker's declared one --
+            // so there is nothing here for `emitCall` to force void from.
+            hostMemberVoidResults: new Set(),
+            hostConstructors: appleHostConstructors(),
+            hostFunctions: appleHostFunctions(),
+            // UIKit and AppKit each declare an `installRootView`, and the flat table
+            // above can hold only one. See `appleHostFunctionsByDeclaration`.
+            hostFunctionsByDeclaration: appleHostFunctionsByDeclaration(),
+            // The Apple packages state no namespace globals: every AppKit entry
+            // point this compiler reaches is a member of a class or a free function,
+            // and a class object is already carried by `nativeTypes`.
+            hostNamespaces: noHostNamespaces,
+            // No namespace roots claimed at all, so no per-file collision to state either.
+            hostNamespaceRootsByDeclaration: new Map(),
+            // No namespace roots, so nothing to state a type for either.
+            hostNamespaceRootTypes: new Map(),
+            // Every AppKit singleton this compiler reaches (`NSApplication.shared`)
+            // is a static member of a class object, which `host-class` already
+            // renders; no global name on this host is one.
+            hostSingletons: new Set(),
+            // No singletons claimed, so no per-file collision to state either.
+            hostSingletonsByDeclaration: new Map(),
+            // AppKit describes its own classes and says nothing about the web
+            // platform's globals; a program that also names one is describing a
+            // second host, and that host is the one that should answer for it.
+            absentGlobals: new Set(),
+            // Apple's declarations arrive through `nativeIncludes` -- one header per
+            // carrier -- rather than per spelling.
+            hostPreambles: new Map(),
+            nativeBases: appleNativeBases(),
+            nativeIncludes: appleNativeIncludes(),
+            nativeConstants: appleNativeConstants(),
+            // `embeddedHostConstants` (host.ts) carries no per-declaration-file
+            // variant the way `embeddedHostFunctionFrameworkVariants` does for
+            // functions -- the package states one ambient value per constant name,
+            // not one per framework -- so there is no collision to state here.
+            hostConstantsByDeclaration: new Map(),
+            // AppKit asks nothing of a generated unit: the target's own `macos_main.mm`
+            // defines every host function this plugin names, and the bridge is written
+            // by the plugin package next to the unit rather than into it.
+            // The unit is compiled against the bridge exactly when the bridge is
+            // written beside it, so this reads the same option `appleBridgeArtifacts`
+            // does, through the same helper: the two are one condition and a build
+            // that got one without the other would either include a header nothing
+            // wrote or write one nothing includes. Not derived from which carriers
+            // the plan selected -- an apple-native app whose program happens to name
+            // no Apple type is still an apple-native app, and the target decides that
+            // by reading this line out of `generated_support.hpp`.
+            generatedSupportIncludes: appleMetadataPath(options) === null ? [] : [appleNativeBridgeHeader],
+            runtimeDefinitions: [],
+            // AppKit/UIKit have no fragment node: a view is added to a superview, and
+            // there is nothing that splices its own children into whatever it is
+            // added to. So this host states none, and `<>...</>` is refused by name
+            // rather than rendered as some other container that would change the
+            // view hierarchy the program asked for.
+            elementFragment: null,
+            elementTextTags: [],
+            // Nothing this host lowers calls a class member the program does not name.
+            reachedMemberKeys: new Set(),
+            // AppKit's own state is not reactive in this sense: a control is read and
+            // written through the host, and nothing in the apple package declares a
+            // base whose fields re-render anything. Stating no fields is the truthful
+            // answer, not a gap -- an empty table is what makes a class here keep
+            // plain members.
+            reactiveClassFields: new Map(),
+            nativeReactiveCell: null,
+            nativeReactiveCellPreamble: []
+        }
+    })
+};