@geastack/compiler 1.0.15

package/dist/plugins/gea/template-analysis.js

@@ -0,0 +1,346 @@
+import { operandOf } from '../../semantics/model/operands.js';
+/**
+ * Split a component's template root into static structure and dynamic slots.
+ *
+ * `root` must be the `ElementOperation` a `template()` body's JSX evaluates to
+ * -- the caller is the one that knows which operation that is (it resolved the
+ * component's render member and found the operation its body publishes); this
+ * function only knows how to walk one, given the graph it belongs to.
+ */
+export const analyzeTemplate = (root, graph) => {
+    // A fragment has no single element to anchor a childNodes-index walk on --
+    // gea handles this by wrapping the whole thing in a synthetic
+    // `<span style="display:contents">`, which is a real DOM decision (an extra
+    // node, a real style) that belongs to whoever builds DOM, not to an
+    // analysis that only describes what the program wrote. A bare component
+    // root (`template() { return <Other/> }`) has the identical problem for the
+    // identical reason: there is no host element in the program's own JSX for
+    // this analysis to describe as the root, only a mount. Both are refused
+    // rather than silently fabricating the wrapper gea would insert.
+    if (root.form !== 'intrinsic') {
+        return {
+            kind: 'blocked',
+            reason: `the template root is a "${root.form}" element, not an intrinsic one; this analysis anchors every slot's walk on a ` +
+                "single host element in the program's own JSX and refuses to fabricate a wrapper for a root that has none"
+        };
+    }
+    const slots = [];
+    const built = buildStaticElement(root, graph, slots, [], []);
+    if (built.kind === 'blocked')
+        return built;
+    return { kind: 'ok', root: built.element, slots };
+};
+/** The operation that published `resultId`, or `null` when the graph has no producer for it (an upstream census block). */
+const producingOperation = (graph, resultId) => {
+    const owner = graph.results.get(resultId);
+    if (owner === undefined)
+        return null;
+    return graph.operations.get(owner) ?? null;
+};
+/** The operation an operand's value comes from, or `null` when the operand is not a `result` citation. */
+const operandProducer = (graph, operand) => operand.source.kind === 'result' ? producingOperation(graph, operand.source.result) : null;
+/**
+ * Whether `operand` is JSX-shaped or an absent literal -- the same test
+ * gea's `isJsxOrNullish` applies to a ternary/logical branch to decide
+ * whether the whole expression is a *conditional element slot* rather than an
+ * ordinary reactive value. An element-family operand is a real JSX
+ * construction (an intrinsic, a component mount, or even a fragment -- any of
+ * which needs a branch-specific sub-template this analysis does not build);
+ * `null` and `undefined` are the other branches a program commonly writes for
+ * "render nothing."
+ * Both absent values are read from the operand's own literal form rather than
+ * from its text, because the string `'null'` spells itself exactly the way the
+ * language's `null` does.
+ */
+const isJsxOrNullish = (graph, operand) => {
+    if (operand.source.kind === 'constant')
+        return operand.source.literal === 'null' || operand.source.literal === 'undefined';
+    const producer = operandProducer(graph, operand);
+    return producer !== null && producer.family === 'element';
+};
+/**
+ * Whether `operand`'s own checked type is an array.
+ *
+ * This is how a list child is recognized -- not by looking for a `.map()`
+ * call, which is a syntax shape this compiler's architecture deliberately
+ * does not carry as identity (an `InvocationOperation` records *that* a call
+ * happened and what its target proof is, never a method name to pattern-match
+ * against). An array-typed value cannot occupy a single reactive DOM
+ * position no matter how it was produced -- `.map()`, `.filter()`, a plain
+ * array literal, a getter -- so reading the operand's own structural type is
+ * both simpler and more complete than trying to special-case one spelling of
+ * "produces an array."
+ */
+const isArrayTyped = (graph, operand) => {
+    const structuralType = graph.structuralTypes.get(operand.type);
+    return structuralType !== undefined && structuralType.shape.kind === 'array';
+};
+/**
+ * Classify one child position. A dynamic position is any operand whose source
+ * is not `constant` -- constant text is static, everything else needs a
+ * closer look at what actually produces it before this analysis can say
+ * whether it is describable at all.
+ */
+const classifyChild = (graph, operand) => {
+    if (operand.source.kind === 'constant')
+        return { kind: 'static-text', text: operand.source.text };
+    if (operand.source.kind !== 'result') {
+        return {
+            kind: 'refuse',
+            reason: `a child operand of source kind "${operand.source.kind}" names no value this analysis can place in the tree`
+        };
+    }
+    const producer = producingOperation(graph, operand.source.result);
+    if (producer === null) {
+        return {
+            kind: 'refuse',
+            reason: 'the child result has no producing operation in the graph, which means an upstream producer blocked it'
+        };
+    }
+    if (producer.family === 'element') {
+        // A spread child (`{...children}`) is already refused at the census level
+        // -- `childrenOf` in semantics/normalize/producers/jsx.ts blocks it before
+        // an operation ever publishes -- so it never reaches here as a citable
+        // result; only a fragment child needs handling of its own.
+        if (producer.form === 'fragment') {
+            return {
+                kind: 'refuse',
+                reason: "a fragment child splices its own children into the parent's walk at the same depth, which needs renumbering every " +
+                    'sibling walk after it; this analysis does not perform that renumbering'
+            };
+        }
+        return producer.form === 'intrinsic' ? { kind: 'static-element', operation: producer } : { kind: 'mount', operation: producer };
+    }
+    if (isArrayTyped(graph, operand)) {
+        return { kind: 'refuse', reason: 'an array-typed child needs per-item keyed reconciliation, which this analysis does not build' };
+    }
+    // A ternary in child position is only a *conditional element* -- the shape
+    // this analysis refuses -- when at least one branch is itself JSX (or the
+    // `null` a program writes for "nothing"). `cond ? 'a' : 'b'` is an ordinary
+    // computed string and is left as a ordinary reactive text slot below,
+    // exactly as gea's own `isJsxOrNullish` gate distinguishes the two.
+    if (producer.family === 'computation' && producer.form === 'conditional') {
+        const consequent = operandOf(producer, 'consequent');
+        const alternate = operandOf(producer, 'alternate');
+        const branchIsElement = (consequent !== undefined && isJsxOrNullish(graph, consequent)) || (alternate !== undefined && isJsxOrNullish(graph, alternate));
+        if (branchIsElement) {
+            return {
+                kind: 'refuse',
+                reason: 'a conditional child with an element branch needs branch-specific sub-templates this analysis does not build'
+            };
+        }
+    }
+    // Same distinction for `cond && <X/>` / `cond && items.map(...)`: only the
+    // right-hand branch matters (the left is the guard, never itself rendered),
+    // and it is refused only when that branch is an element or a list.
+    if (producer.family === 'computation' && producer.form === 'logical') {
+        const right = operandOf(producer, 'right');
+        const guardsElementOrList = right !== undefined && (isJsxOrNullish(graph, right) || isArrayTyped(graph, right));
+        if (guardsElementOrList) {
+            return {
+                kind: 'refuse',
+                reason: 'a short-circuit child guarding an element or list branch needs a conditional/list sub-template this analysis does not build'
+            };
+        }
+    }
+    return { kind: 'dynamic-text' };
+};
+/**
+ * Build one static element node, recording every dynamic slot it or its
+ * static-element descendants own into `slots` (mutated in place -- this is
+ * the function's own scratch accumulator, not anything the caller handed in,
+ * so it stays consistent with "no mutation of anything given").
+ *
+ * Called only with `operation.form === 'intrinsic'`: `analyzeTemplate` checks
+ * the root before the first call, and `classifyChild` only ever routes a
+ * *recursive* call here for a child it classified `'static-element'`, which
+ * by construction is the `form === 'intrinsic'` branch.
+ *
+ * Attributes are recorded before children, and children are walked in source
+ * order with a nested static element's own attributes and children recorded
+ * immediately on recursion -- so slot `index` assignment is a plain pre-order
+ * walk of the tree, exactly matching the order gea's `emitElement` visits an
+ * element's attributes then its children.
+ */
+const buildStaticElement = (operation, graph, slots, walk, walkKinds) => {
+    const tagOperand = operandOf(operation, 'tag', 0);
+    if (tagOperand === undefined || tagOperand.source.kind !== 'constant') {
+        return { kind: 'blocked', reason: 'an intrinsic element with no constant tag operand is not one this analysis can name statically' };
+    }
+    const attributes = [];
+    const propKeys = operation.operands.filter((candidate) => candidate.role === 'prop-key').sort((a, b) => a.ordinal - b.ordinal);
+    for (const keyOperand of propKeys) {
+        if (keyOperand.source.kind !== 'constant') {
+            return { kind: 'blocked', reason: 'a computed attribute key is not one this analysis can name statically' };
+        }
+        const valueOperand = operandOf(operation, 'prop-value', keyOperand.ordinal);
+        if (valueOperand === undefined) {
+            return { kind: 'blocked', reason: `attribute "${keyOperand.source.text}" has no paired value operand` };
+        }
+        if (valueOperand.source.kind === 'constant') {
+            attributes.push({ name: keyOperand.source.text, value: valueOperand.source.text });
+            continue;
+        }
+        if (valueOperand.source.kind !== 'result') {
+            return {
+                kind: 'blocked',
+                reason: `attribute "${keyOperand.source.text}" has a value of source kind "${valueOperand.source.kind}", which this analysis does not describe`
+            };
+        }
+        slots.push({
+            index: slots.length,
+            kind: classifyAttrKind(keyOperand.source.text),
+            walk: [...walk],
+            walkKinds: [...walkKinds],
+            attributeName: keyOperand.source.text,
+            operand: valueOperand
+        });
+    }
+    const children = [];
+    const childOperands = operation.operands.filter((candidate) => candidate.role === 'child').sort((a, b) => a.ordinal - b.ordinal);
+    let childIndex = 0;
+    let elementIndex = 0;
+    for (const childOperand of childOperands) {
+        const classification = classifyChild(graph, childOperand);
+        if (classification.kind === 'refuse')
+            return { kind: 'blocked', reason: classification.reason };
+        if (classification.kind === 'static-text') {
+            // A text node is a real childNodes entry but never an element, so it
+            // advances childIndex for any slot that follows it without advancing
+            // elementIndex.
+            children.push({ kind: 'text', text: classification.text });
+            childIndex += 1;
+            continue;
+        }
+        const childWalk = [...walk, childIndex];
+        if (classification.kind === 'static-element') {
+            const nested = buildStaticElement(classification.operation, graph, slots, childWalk, [...walkKinds, { elem: elementIndex }]);
+            if (nested.kind === 'blocked')
+                return nested;
+            children.push(nested.element);
+            elementIndex += 1;
+            childIndex += 1;
+            continue;
+        }
+        // 'mount' and 'dynamic-text' both occupy a non-element childNodes
+        // position (a mounted component has no element of its own in *this*
+        // template -- its own template is a separate analysis the caller runs on
+        // its own root), so both advance childIndex but not elementIndex, and
+        // both record `{child: childIndex}` as their final walkKinds step.
+        slots.push({
+            index: slots.length,
+            kind: classification.kind === 'mount' ? 'mount' : 'text',
+            walk: childWalk,
+            walkKinds: [...walkKinds, { child: childIndex }],
+            attributeName: null,
+            operand: childOperand
+        });
+        children.push({ kind: 'anchor', slotIndex: slots.length - 1 });
+        childIndex += 1;
+    }
+    return { kind: 'ok', element: { kind: 'element', tag: tagOperand.source.text, attributes, children } };
+};
+/**
+ * gea's own DOM event vocabulary (`packages/vite-plugin-gea/src/utils/events.ts`,
+ * `EVENT_NAMES`): bare event names a program may write directly (`click`,
+ * `input`, ...) as well as the conventional `on*` prefix form. This table,
+ * like `classifyAttrKind` itself, is library policy -- a fact about what gea
+ * chose to call its events, not a fact this compiler's semantic graph states.
+ */
+const EVENT_ATTRIBUTE_NAMES = new Set([
+    'click',
+    'dblclick',
+    'mousedown',
+    'mouseup',
+    'mouseover',
+    'mouseout',
+    'mousemove',
+    'mouseenter',
+    'mouseleave',
+    'contextmenu',
+    'keydown',
+    'keyup',
+    'keypress',
+    'focus',
+    'blur',
+    'input',
+    'change',
+    'submit',
+    'scroll',
+    'touchstart',
+    'touchmove',
+    'touchend',
+    'tap',
+    'longTap',
+    'swipeRight',
+    'swipeUp',
+    'swipeLeft',
+    'swipeDown',
+    'drag',
+    'dragstart',
+    'dragend',
+    'dragover',
+    'dragleave',
+    'drop',
+    'pointerdown',
+    'pointerup',
+    'pointermove',
+    'pointerenter',
+    'pointerleave',
+    'pointerover',
+    'pointerout',
+    'pointercancel',
+    'resize',
+    'reset',
+    'wheel',
+    'animationstart',
+    'animationend',
+    'animationiteration',
+    'transitionstart',
+    'transitionend',
+    'transitionrun',
+    'transitioncancel'
+]);
+/** Attribute names gea reflects as an IDL boolean property rather than a string attribute. */
+const BOOLEAN_ATTRIBUTE_NAMES = new Set([
+    'disabled',
+    'checked',
+    'readonly',
+    'readOnly',
+    'hidden',
+    'required',
+    'autofocus',
+    'multiple',
+    'selected',
+    'open',
+    'indeterminate',
+    'contenteditable',
+    'contentEditable'
+]);
+/**
+ * gea's attribute-name -> slot-kind table (mirrors `classifyAttrKind` in
+ * `packages/vite-plugin-gea/src/closure-codegen/generator/generator-attrs.ts`).
+ * See the `AttributeSlotKind` doc comment above for why this policy belongs
+ * in this file rather than in the core.
+ */
+const classifyAttrKind = (name) => {
+    if (EVENT_ATTRIBUTE_NAMES.has(name))
+        return 'event';
+    if (name.startsWith('on') && name.length > 2)
+        return 'event';
+    if (name === 'class' || name === 'className')
+        return 'class';
+    if (name === 'style')
+        return 'style';
+    if (name === 'value')
+        return 'value';
+    if (name === 'visible')
+        return 'bool';
+    if (name === 'ref')
+        return 'ref';
+    if (name === 'dangerouslySetInnerHTML')
+        return 'html';
+    if (BOOLEAN_ATTRIBUTE_NAMES.has(name))
+        return 'bool';
+    return 'attr';
+};

package/dist/plugins/gea/user-agent-styles.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The registration block, as one C++ statement block.
+ *
+ * A block rather than a free function so it can be dropped into either prelude
+ * form -- the static-initialization object a single-app binary gets, or the
+ * named `<prefix>_register_styles()` a resident build calls when its app
+ * starts -- without either form having to know what is in it.
+ */
+export declare const geaUserAgentStyleSheet: string;

package/dist/plugins/gea/user-agent-styles.js

@@ -0,0 +1,94 @@
+/**
+ * gea's user-agent stylesheet.
+ *
+ * The engine has no default stylesheet. `Document::createElement(tag)`
+ * (`core/packages/engine/ui/document.cpp`) maps a handful of tags to typed
+ * creators, stamps the tag name, and stops -- so a `<p>` and a `<div>` reach
+ * layout with byte-identical style state. Everything a browser's UA sheet would
+ * say about a tag has to be said by somebody else, and in v1 that somebody is
+ * the compiler: `intrinsicStyleLines` in the gea plugin's
+ * `cpp-template-renderer.ts` emits `Tree::setDefaultStyle` calls next to the
+ * node it just built.
+ *
+ * v2 emitted none of them, and the visible result was the `typography` app's
+ * intro paragraph: `<p>` + three `<span>`s rendered as narrow columns of one
+ * character each instead of a line of prose. The stylesheet was NOT the
+ * difference -- `gea-style-registration.cppfrag` is produced by the shared
+ * build pipeline and is byte-identical between the two compilers -- and neither
+ * were the tags: v2 spells `gea::jsx::create<NodeHandle>("span")` and the
+ * engine's `isInlineLevelTag` recognises it. What was missing was one bit.
+ *
+ * `LayoutNodePass::resolveRowDirection` (`ui/layout.cpp`) already builds the
+ * inline formatting context: a plain block whose in-flow children are all
+ * inline-level flows them on a ROW, the way CSS says. But the row it hands to
+ * `FlexLayoutPass` is only allowed to break into lines when
+ * `node.style.flex_wrap` is set, and nothing sets it -- so every inline run
+ * landed on one unbreakable line, each item shrunk to a sliver. v1 never sees
+ * this because it writes `display:flex / flex-direction:row / flex-wrap:wrap`
+ * onto exactly those containers. `flex-wrap` is the whole of the fix; the other
+ * two only restate what `resolveRowDirection` already worked out, and stating
+ * `display:flex` here would be actively wrong -- it would make a `<span>`
+ * non-inline-level (`isInlineLevelNode` rejects a flex node), which is the one
+ * thing that would stop its parent forming an inline row at all.
+ *
+ * Expressed as CSS rather than as per-node default styles because that is what
+ * it is -- and because the cascade already ranks it correctly. The engine
+ * implements real specificity (`computeRuleSpecificity`, `ui/style.cpp`: id
+ * 10000 / class 100 / element 1, ties by source order), so an element-selector
+ * rule registered before the app's own tape loses to every class rule the app
+ * writes and to the app's own element rules. That is the same "lowest priority,
+ * overridable by anything the author says" tier `setDefaultStyle` occupies in
+ * v1, without the compiler having to reach into a node it did not build.
+ *
+ * The tag set and the heading sizes are v1's, verbatim (`isTextNodeTag` and
+ * `headingDefaultFontSize`), because the two compilers have to put the same
+ * pixels on the same panel.
+ */
+const inlineContainerTags = ['p', 'span', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6'];
+/** v1's `headingDefaultFontSize`, in px. */
+const headingFontSizes = [
+    ['h1', 34],
+    ['h2', 28],
+    ['h3', 24],
+    ['h4', 20],
+    ['h5', 18],
+    ['h6', 16]
+];
+const cppTagList = (tags) => tags.map((tag) => `"${tag}"`).join(', ');
+const cppHeadingList = (sizes) => sizes.map(([tag, size]) => `{"${tag}", ${size}}`).join(', ');
+/**
+ * The registration block, as one C++ statement block.
+ *
+ * A block rather than a free function so it can be dropped into either prelude
+ * form -- the static-initialization object a single-app binary gets, or the
+ * named `<prefix>_register_styles()` a resident build calls when its app
+ * starts -- without either form having to know what is in it.
+ */
+export const geaUserAgentStyleSheet = [
+    '// gea user-agent defaults: the tag-driven styles the engine has no sheet for.',
+    "// Registered BEFORE the app's own rules so equal-specificity ties go to the app.",
+    '{',
+    '  namespace __gea_ua_ns = gea::embedded::ui;',
+    '  auto &__gea_ua_sheet = __gea_ua_ns::StyleSheet::instance();',
+    '  __gea_ua_sheet.beginRuleRegistrationBatch();',
+    '  // An inline formatting context wraps. `resolveRowDirection` (ui/layout.cpp)',
+    '  // already flows an all-inline block on a row; without this the row cannot',
+    '  // break, and a paragraph of text and spans renders as slivered columns.',
+    `  static const char *const __gea_ua_inline_tags[] = {${cppTagList(inlineContainerTags)}};`,
+    '  for (const char *const __gea_ua_tag : __gea_ua_inline_tags) {',
+    '    __gea_ua_sheet.registerStaticPropertyRule(',
+    '      __gea_ua_ns::StaticStyleSelectorKind::Element, __gea_ua_tag, __gea_ua_ns::Property::FlexWrap, 1);',
+    '  }',
+    "  // Heading sizes, v1's `headingDefaultFontSize` verbatim.",
+    '  static const struct { const char *tag; float size; } __gea_ua_headings[] = {',
+    `    ${cppHeadingList(headingFontSizes)}`,
+    '  };',
+    '  for (const auto &__gea_ua_heading : __gea_ua_headings) {',
+    '    __gea_ua_sheet.registerStaticLengthRule(',
+    '      __gea_ua_ns::StaticStyleSelectorKind::Element, __gea_ua_heading.tag,',
+    '      __gea_ua_ns::StaticStyleLengthProperty::FontSize, __gea_ua_ns::StaticStyleLengthUnit::Px,',
+    '      __gea_ua_heading.size);',
+    '  }',
+    '  __gea_ua_sheet.endRuleRegistrationBatch();',
+    '}'
+].join('\n');

package/dist/plugins/installed.d.ts

@@ -0,0 +1,19 @@
+import type { CompilerPlugin } from './model.js';
+/**
+ * The plugins this build installs.
+ *
+ * Empty would be a real answer, and the one a compiler with no library in front
+ * of it should give: a program whose JSX names a value is then refused by name,
+ * at preflight, instead of being lowered by a guess about what that value
+ * meant. gea is installed here because gea is what this build compiles for,
+ * and apple-native beside it because the same corpus contains programs written
+ * against AppKit rather than against gea's own element tree. Two hosts, not one
+ * host with a second mode: each states its own type table, and a program that
+ * names neither is unaffected by both.
+ *
+ * native-webgl-angle is the third, and the one that shows how little a host has
+ * to state when the compiler can read the library itself: it names 127 free
+ * functions and no types at all, because the WebGL context a three.js program
+ * holds is a TypeScript class this compiler compiles. See `webgl/plugin.ts`.
+ */
+export declare const installedPlugins: readonly CompilerPlugin[];

package/dist/plugins/installed.js

@@ -0,0 +1,21 @@
+import { applePlugin } from './apple/plugin.js';
+import { geaPlugin } from './gea/plugin.js';
+import { webglPlugin } from './webgl/plugin.js';
+/**
+ * The plugins this build installs.
+ *
+ * Empty would be a real answer, and the one a compiler with no library in front
+ * of it should give: a program whose JSX names a value is then refused by name,
+ * at preflight, instead of being lowered by a guess about what that value
+ * meant. gea is installed here because gea is what this build compiles for,
+ * and apple-native beside it because the same corpus contains programs written
+ * against AppKit rather than against gea's own element tree. Two hosts, not one
+ * host with a second mode: each states its own type table, and a program that
+ * names neither is unaffected by both.
+ *
+ * native-webgl-angle is the third, and the one that shows how little a host has
+ * to state when the compiler can read the library itself: it names 127 free
+ * functions and no types at all, because the WebGL context a three.js program
+ * holds is a TypeScript class this compiler compiles. See `webgl/plugin.ts`.
+ */
+export const installedPlugins = [geaPlugin, applePlugin, webglPlugin];

package/dist/plugins/load.d.ts

@@ -0,0 +1,7 @@
+import { type CompilerPlugin } from './model.js';
+/**
+ * Built-ins retain their order; explicit plugins follow in flag order. The
+ * compiler API owns capability and hook precedence. Duplicate module paths
+ * (including symlinks) load once; distinct definitions of one name fail.
+ */
+export declare const loadCliPlugins: (specifiers: readonly string[]) => Promise<readonly CompilerPlugin[]>;