@octane-xplat/nativescript-mason-core 0.0.1 → 1.0.0-beta.1

package/index.d.ts

@@ -0,0 +1,12 @@
+/// <reference path="./typings/native.d.ts" />
+export { View } from './view';
+export { Scroll } from './scroll';
+export { ViewBase, Event } from './common';
+export type { ScrollBehavior, ScrollLogicalPosition, ScrollToOptions, ScrollIntoViewOptions } from './common';
+export { Style } from './style';
+export { setCssEnvironment, clearCssEnvironment, bindCssEnvironment, refreshCssEnvironment } from './css-environment';
+export type { CssSafeAreaInsets, CssEnvironmentHost, CssEnvironmentSource } from './css-environment';
+export { setCssDiagnostics, getCssDiagnostics, clearCssDiagnostics, formatCssDiagnostics, cssDiagnosticsEnabled } from './diagnostics';
+export { setCssUnitContext, cssUnits } from './units';
+export { registerAppFontsDirectory } from './fonts';
+export type * from './layout-types';

package/index.ios.d.ts

@@ -0,0 +1,11 @@
+export { View } from './view';
+export { Scroll } from './scroll';
+export { ViewBase, Event } from './common';
+export type { ScrollBehavior, ScrollLogicalPosition, ScrollToOptions, ScrollIntoViewOptions } from './common';
+export { Style } from './style';
+export { setCssEnvironment, clearCssEnvironment, bindCssEnvironment, refreshCssEnvironment } from './css-environment';
+export type { CssSafeAreaInsets, CssEnvironmentHost, CssEnvironmentSource } from './css-environment';
+export { setCssDiagnostics, getCssDiagnostics, clearCssDiagnostics, formatCssDiagnostics, cssDiagnosticsEnabled } from './diagnostics';
+export { setCssUnitContext, cssUnits } from './units';
+export { registerAppFontsDirectory } from './fonts';
+export type * from './layout-types';

package/index.ios.js

@@ -0,0 +1,9 @@
+/// <reference path="./typings/native.d.ts" />
+export { View } from './view';
+export { Scroll } from './scroll';
+export { ViewBase, Event } from './common';
+export { Style } from './style';
+export { setCssEnvironment, clearCssEnvironment, bindCssEnvironment, refreshCssEnvironment } from './css-environment';
+export { setCssDiagnostics, getCssDiagnostics, clearCssDiagnostics, formatCssDiagnostics, cssDiagnosticsEnabled } from './diagnostics';
+export { setCssUnitContext, cssUnits } from './units';
+export { registerAppFontsDirectory } from './fonts';

package/ios-host-README.md

@@ -0,0 +1,124 @@
+# Core iOS host prototype
+
+The core-only simulator framework builds and runs without MasonKit's HTML
+parser, rich-text renderer, or widget classes. It is a native boundary proof;
+NativeScript metadata and npm plugin packaging are separate proofs; see
+`tools/mason-core/plugin-README.md` in the source checkout.
+
+## Build and inspect the artifact
+
+On macOS with Xcode and the repository's Rust iOS prerequisites installed:
+
+```sh
+pnpm exec nx run nativescript-mason-core:verify.host.ios.artifact
+```
+
+The target builds the independent Rust engine, generates the core Swift project
+under `tmp/mason-core-ios-host`, and exports
+`dist/native/mason-core/ios-host/release`. Verification copies the artifact to an
+isolated temporary directory, links Swift and Objective-C consumers, verifies
+all 99 declared C functions are exported, and checks native symbols and headers
+for excluded classes.
+
+Build and verify the unsigned arm64 device framework separately:
+
+```sh
+pnpm exec nx run nativescript-mason-core:verify.host.ios.device.artifact
+```
+
+This uses `iphoneos`, the device engine archive and separate staging/derived
+folders, exporting `dist/native/mason-core/ios-host/device/release`. The device
+framework and isolated Swift/Objective-C clients compile and link; its Mach-O
+platform and all 99 C exports are verified. This is build evidence only. It does
+not qualify device runtime behavior.
+Both builds require a native-build resource reservation. Assemble the verified
+slices after both builds:
+
+```sh
+pnpm exec nx run nativescript-mason-core:build.host.ios.xcframework
+```
+
+Assembly requires matching source hashes, dependency locks and public headers.
+It exports `dist/native/mason-core/ios-host/universal`, embedding each platform's
+SDWebImage privacy bundle in its own framework slice. The plugin packages this
+XCFramework; resource paths no longer depend on a simulator-only global bundle.
+
+The exported framework retains FontManager for styling/font metrics and
+SDWebImage for container backgrounds and nine-slice images. Their code is
+linked into the framework. Their dependency headers and licenses accompany it;
+FontManager's Clang module is required even for a Swift client that imports
+only `MasonCore`. Removing image/text widgets does not remove these remaining
+callers. The export also carries SwiftPM's SDWebImage resource/privacy bundle.
+The separate isolated NativeScript app verifies resource discovery, core class
+metadata, layout and ownership on an arm64 simulator. Independent public native
+declarations are generated independently; device app coverage remains a gate.
+
+## Run native layout tests
+
+Build the test bundle first:
+
+```sh
+pnpm exec nx run nativescript-mason-core:build.tests.ios
+```
+
+Prepare a dedicated simulator and record its identifier. This example uses the
+iOS 27 runtime and iPhone 17 Pro device type used for the current proof; inspect
+`xcrun simctl list` for identifiers installed on another machine.
+
+```sh
+test -f tmp/mason-core-ios-test-device.txt || \
+  xcrun simctl create 'Mason core extraction' \
+    com.apple.CoreSimulator.SimDeviceType.iPhone-17-Pro \
+    com.apple.CoreSimulator.SimRuntime.iOS-27-0 > tmp/mason-core-ios-test-device.txt
+pnpm exec nx run nativescript-mason-core:test.host.ios
+```
+
+The runner boots only that dedicated device and shuts it down afterward. It
+runs the 11 existing `CoreLayoutInteropTests` unchanged apart from their module
+import, plus four core regressions. It checks the result bundle contains all
+15 passing tests, with no skips. Results stay under `tmp/mason-core-ios-tests`.
+The tests exercise UIKit directly; they do not capture screenshots.
+
+Covered behavior: grid placement, foreign label intrinsic-size invalidation,
+percentage sizing and reset, programmatic scroll clamping, nested roots during
+an outer compute, bounded root measurement, and view/node/listener release.
+Host-driven fixtures give roots explicit bounds and mark their applied compute
+before programmatic seeking, matching the host lifecycle.
+
+## Preserve source and the full package
+
+The generated project compiles 39 existing Swift files. Of these, 25 retain
+identical source bytes; 14 have explicit core-only adaptations. The manifest
+records each original and projected hash. The 25 unchanged files now live in
+core after byte-preserving `git mv` moves. The full Xcode project changes only
+those source references; its implementation and remaining files retain their
+bytes. No full-to-core runtime dependency is added.
+
+`ios-sources.mjs` uses compiler-derived declaration spans from `swift-source.mjs`
+to remove optional factories, HTML conveniences, text-run reconciliation, and
+widget-specific branches. `ios-node-children.swift` supplies the foreign-view
+and container child operations. Shared measurement methods remain unchanged.
+This projection is temporary prototype wiring, not the final upstream seam.
+The native path mapping and baseline hashes live in `native-relocations.json`.
+Generated projects reconstruct the original source layout; both builds resolve
+one tracked copy through `native-sources.mjs`. Keep future fixes separate from
+source moves and avoid parallel edited copies.
+
+Container painting and scrolling remain in core. Background text clipping has
+a small native glyph-provider protocol, allowing a renderer to supply outlines
+without embedding MasonKit's text renderer. Ordinary UIKit/NativeScript labels
+do not acquire glyph-provider support from this extraction. The shared Rust
+engine and C interface still contain inline-layout code and convenience node
+constructors; this proof does not claim those costs have been removed.
+
+## Remaining qualification
+
+The native host exports separate arm64 simulator and device frameworks.
+The plugin packages both slices. Its compiled simulator app qualifies bridge
+metadata, framework-local resources and OS input; the unsigned device app build
+checks device metadata and resource selection separately. Physical iOS device
+execution remains unqualified. Simulator bridge types,
+plugin discovery, compiled components and OS input pass separately; see the
+[plugin proof](plugin-README.md). Matching release app size measurements remain. Core and full MasonKit are separate-host choices;
+coinstallation and native ABI compatibility are not qualified. Windows is not
+qualified by this prototype.

package/layout-types.d.ts

@@ -0,0 +1,192 @@
+import type { Color, CoreTypes } from '@nativescript/core';
+import type { LengthPercentage } from '@nativescript/core/css/parser';
+
+
+/**
+ * A CSS length. `px` is a CSS pixel — the same size as a dip, exactly as on the
+ * web — and a bare number is also dip. `dppx` is the escape hatch for a literal
+ * device pixel; note this differs from `@nativescript/core`, where `px` itself
+ * means a device pixel.
+ */
+export type Length = CoreTypes.dip | CoreTypes.LengthDipUnit | CoreTypes.LengthPxUnit | CoreTypes.LengthPercentUnit | `${number}px` | `${number}%` | `${number}dip` | `${number}dppx`;
+
+
+export type LengthAuto = CoreTypes.dip | CoreTypes.LengthDipUnit | CoreTypes.LengthPxUnit | CoreTypes.LengthPercentUnit | 'auto' | `${number}px` | `${number}%` | `${number}dip` | `${number}dppx`;
+
+
+export type DimensionKeyword = 'min-content' | 'max-content' | 'fit-content' | 'stretch' | 'content' | `fit-content(${string})`;
+
+
+export type DimensionLength = LengthAuto | DimensionKeyword;
+
+
+export type SizeLength = { width: Length; height: Length };
+
+
+export type Position = 'static' | 'relative' | 'absolute' | 'fixed' | 'sticky';
+
+
+export type Display = 'none' | 'flex' | 'grid' | 'block' | 'inline' | 'inline-block' | 'inline-flex' | 'inline-grid';
+
+
+export type BoxSizing = 'border-box' | 'content-box';
+
+
+export type Overflow = 'visible' | 'hidden' | 'scroll' | 'clip' | 'auto';
+
+
+export type FlexWrap = 'nowrap' | 'no-wrap' | 'wrap' | 'wrap-reverse' | 'balance' | 'balance-reverse';
+
+
+export type FlexDirection = 'column' | 'row' | 'column-reverse' | 'row-reverse';
+
+
+export type GapTypeUnit = `px` | 'dip' | '%';
+
+
+export type Gap = Length | `${string}${GapTypeUnit} ${string}${GapTypeUnit}`;
+
+
+export type AlignItems = 'normal' | 'flex-start' | 'flex-end' | 'start' | 'end' | 'center' | 'baseline' | 'stretch';
+
+
+export type AlignSelf = 'normal' | 'flex-start' | 'flex-end' | 'start' | 'end' | 'center' | 'baseline' | 'stretch';
+
+
+export type AlignContent = 'normal' | 'flex-start' | 'flex-end' | 'start' | 'end' | 'center' | 'stretch' | 'space-between' | 'space-around' | 'space-evenly';
+
+
+export type JustifyItems = AlignItems;
+
+
+export type JustifySelf = AlignSelf;
+
+
+export type JustifyContent = AlignContent;
+
+
+export type GridAutoFlow = 'row' | 'column' | 'row dense' | 'column dense' | 'dense';
+
+
+export type VerticalAlign = 'baseline' | 'sub' | 'super' | 'text-top' | 'text-bottom' | 'middle' | 'top' | 'bottom' | Length | number;
+
+
+export type Float = 'left' | 'right' | 'none';
+
+
+export type Clear = 'left' | 'right' | 'both' | 'none';
+
+
+declare module '@nativescript/core/ui/styling/style' {
+  interface Style {
+    boxSizing: BoxSizing;
+    display: Display;
+    position: Position;
+    flexDirection: FlexDirection;
+    flexWrap: FlexWrap;
+    flex: string | 'auto' | 'none' | number | 'initial';
+    flexFlow: string;
+    minWidth: LengthAuto;
+    minHeight: LengthAuto;
+    width: DimensionLength;
+    height: DimensionLength;
+    maxWidth: LengthAuto;
+    maxHeight: LengthAuto;
+    left: LengthAuto;
+    right: LengthAuto;
+    top: LengthAuto;
+    bottom: LengthAuto;
+    gridGap: Gap;
+    gap: Gap;
+    rowGap: Length;
+    columnGap: Length;
+    aspectRatio: number;
+    flexBasis: LengthPercentage | DimensionKeyword | string | number;
+    alignItems: AlignItems;
+    alignSelf: AlignSelf;
+    alignContent: AlignContent;
+    justifyItems: JustifyItems;
+    justifySelf: JustifySelf;
+    justifyContent: JustifyContent;
+    gridAutoRows: string;
+    gridAutoColumns: string;
+    gridAutoFlow: GridAutoFlow;
+    gridRowGap: Gap;
+    gridColumnGap: Gap;
+    gridArea: string;
+    gridColumn: string;
+    gridColumnStart: string;
+    gridColumnEnd: string;
+    gridRow: string;
+    gridRowStart: string;
+    gridRowEnd: string;
+    gridTemplateRows: string;
+    gridTemplateColumns: string;
+    gridTemplateAreas: string;
+    textOverflow: 'clip' | 'ellipsis' | string;
+    textWrap: 'nowrap' | 'wrap' | 'balance';
+    textTransform: 'none' | 'capitalize' | 'uppercase' | 'lowercase';
+    overflow: Overflow | `${Overflow} ${Overflow}`;
+    overflowX: Overflow;
+    overflowY: Overflow;
+    scrollBarWidth: Length;
+    verticalAlign: VerticalAlign;
+    cornerShape: string;
+    cornerShapeTopLeft: string;
+    cornerShapeTopRight: string;
+    cornerShapeBottomRight: string;
+    cornerShapeBottomLeft: string;
+    objectPosition: string;
+    borderStyle: string;
+    borderLeftStyle: string;
+    borderRightStyle: string;
+    borderTopStyle: string;
+    borderBottomStyle: string;
+    borderImage: string;
+    fontStretch: string;
+    fontFeatureSettings: string;
+    wordSpacing: string;
+    hyphens: 'none' | 'manual' | 'auto';
+    textIndent: string;
+    lineClamp: number | 'none';
+    transformOrigin: string;
+    placeItems: string;
+    placeContent: string;
+    placeSelf: string;
+    listStyle: string;
+    marginInline: string;
+    marginBlock: string;
+    paddingInline: string;
+    paddingBlock: string;
+    insetInline: string;
+    insetBlock: string;
+    inlineSize: string;
+    blockSize: string;
+    writingMode: 'horizontal-tb' | 'vertical-rl' | 'vertical-lr';
+    unicodeBidi: 'normal' | 'embed' | 'bidi-override';
+    backdropFilter: string;
+    maskImage: string;
+    maskSize: string;
+    maskPosition: string;
+    maskRepeat: string;
+    maskOrigin: string;
+    maskClip: string;
+    maskMode: string;
+    maskComposite: string;
+    clipPath: string;
+    maskBorderSource: string;
+    maskBorderSlice: string;
+    maskBorderWidth: string;
+    maskBorderOutset: string;
+    maskBorderRepeat: string;
+    maskBorderMode: string;
+    caretColor: string | Color;
+  }
+}
+
+
+export type ScrollBehavior = 'auto' | 'instant' | 'smooth';
+
+export type ScrollLogicalPosition = 'start' | 'center' | 'end' | 'nearest';
+
+export type BoxShadowRenderMode = 'auto' | 'render-node' | 'software';

package/mask.d.ts

@@ -0,0 +1,54 @@
+/** What the encoder needs from the element's style. */
+export interface WindowsMaskContext {
+    /** A CSS length (not a percentage) in DIPs, or undefined. */
+    length(token: string): number | undefined;
+    /** A CSS colour as 0xAARRGGBB, or null. */
+    color(value: string): number | null;
+    linear(value: string): {
+        angle: number;
+        corner?: [number, number];
+        offsets: number[];
+        colors: number[];
+        positions?: Array<number | null>;
+        lengths?: Array<number | null>;
+    } | null;
+    radial(value: string): {
+        cx: number;
+        cy: number;
+        rx: number;
+        ry: number;
+        offsets: number[];
+        colors: number[];
+        positions?: Array<number | null>;
+        lengths?: Array<number | null>;
+        circle?: number;
+        circleRadius?: number;
+    } | null;
+    /** A url() target as a path or data URI the native side can load. */
+    source(url: string): string;
+}
+/** background-origin / background-clip keywords; the CSS defaults are padding-box and border-box. */
+export interface WindowsBackgroundBoxes {
+    origin?: string;
+    clip?: string;
+}
+/** The background-* longhands, each a comma-separated per-layer list. */
+export interface WindowsBackgroundLonghands {
+    image: string;
+    size?: string;
+    position?: string;
+    repeat?: string;
+    origin?: string;
+    clip?: string;
+    attachment?: string;
+    blend?: string;
+}
+export declare const WINDOWS_MASK_PROPERTIES: ReadonlySet<string>;
+export declare function encodeWindowsMask(_css: ReadonlyMap<string, string>, _ctx: WindowsMaskContext): string;
+export declare function encodeWindowsBackground(_url: string, _size: string, _position: string, _repeat: string, _ctx: WindowsMaskContext, _boxes?: WindowsBackgroundBoxes): string;
+export declare function encodeWindowsGradientBackground(_gradient: string, _size: string, _position: string, _repeat: string, _ctx: WindowsMaskContext, _boxes?: WindowsBackgroundBoxes): string;
+export declare function encodeWindowsColorClip(_clip: string, _ctx: WindowsMaskContext): string;
+export declare function needsWindowsBackgroundLayers(_css: WindowsBackgroundLonghands): boolean;
+export declare function encodeWindowsBackgroundLayers(_css: WindowsBackgroundLonghands, _ctx: WindowsMaskContext): string;
+export declare function hasCustomBackgroundBoxes(_boxes: WindowsBackgroundBoxes): boolean;
+export declare function encodeWindowsBorderImage(_value: string, _ctx: WindowsMaskContext): string;

package/mask.js

@@ -0,0 +1,26 @@
+// Windows only (mask.windows.ts); iOS and Android parse masks natively.
+export const WINDOWS_MASK_PROPERTIES = new Set();
+export function encodeWindowsMask(_css, _ctx) {
+    return '';
+}
+export function encodeWindowsBackground(_url, _size, _position, _repeat, _ctx, _boxes = {}) {
+    return '';
+}
+export function encodeWindowsGradientBackground(_gradient, _size, _position, _repeat, _ctx, _boxes = {}) {
+    return '';
+}
+export function encodeWindowsColorClip(_clip, _ctx) {
+    return '';
+}
+export function needsWindowsBackgroundLayers(_css) {
+    return false;
+}
+export function encodeWindowsBackgroundLayers(_css, _ctx) {
+    return '';
+}
+export function hasCustomBackgroundBoxes(_boxes) {
+    return false;
+}
+export function encodeWindowsBorderImage(_value, _ctx) {
+    return '';
+}

package/native-environment.android.d.ts

@@ -0,0 +1,3 @@
+import type { View } from '@nativescript/core';
+import type { CssEnvironmentSource } from './css-environment';
+export declare function nativeCssEnvironmentSource(view: View): CssEnvironmentSource;

package/native-environment.android.js

@@ -0,0 +1,69 @@
+const roots = new WeakMap();
+function readInsets(root) {
+    const native = root?.getRootWindowInsets();
+    if (!native)
+        return null;
+    // AndroidX is already a native core dependency. Its systemBars type excludes IME,
+    // including on API 23-29 where raw systemWindowInsetBottom can contain the keyboard.
+    const compat = androidx.core.view.WindowInsetsCompat.toWindowInsetsCompat(native, root);
+    const types = androidx.core.view.WindowInsetsCompat.Type;
+    const insets = compat.getInsets(types.systemBars() | types.displayCutout());
+    const density = root.getResources().getDisplayMetrics().density;
+    return { top: insets.top / density, right: insets.right / density, bottom: insets.bottom / density, left: insets.left / density };
+}
+function observeRoot(root, changed) {
+    let observation = roots.get(root);
+    if (!observation) {
+        const callbacks = new Set();
+        let previous = JSON.stringify(readInsets(root));
+        const listener = new android.view.ViewTreeObserver.OnPreDrawListener({
+            onPreDraw() {
+                const next = JSON.stringify(readInsets(root));
+                if (next !== previous) {
+                    previous = next;
+                    for (const callback of Array.from(callbacks))
+                        callback();
+                }
+                return true;
+            },
+        });
+        const observer = root.getViewTreeObserver();
+        observation = { callbacks, observer, listener };
+        roots.set(root, observation);
+        observer.addOnPreDrawListener(listener);
+        // Observe without replacing anyone's OnApplyWindowInsetsListener or consuming insets.
+        root.requestApplyInsets();
+    }
+    observation.callbacks.add(changed);
+    const current = observation;
+    return () => {
+        current.callbacks.delete(changed);
+        if (!current.callbacks.size) {
+            const observer = current.observer.isAlive() ? current.observer : root.getViewTreeObserver();
+            observer.removeOnPreDrawListener(current.listener);
+            roots.delete(root);
+        }
+    };
+}
+export function nativeCssEnvironmentSource(view) {
+    const rootOfView = () => view.nativeViewProtected?.getRootView();
+    return {
+        read: () => readInsets(rootOfView()),
+        subscribe(changed) {
+            let root;
+            let stop;
+            const select = () => {
+                const next = rootOfView();
+                if (next !== root) {
+                    stop?.();
+                    root = next;
+                    stop = next ? observeRoot(next, changed) : undefined;
+                }
+                changed();
+            };
+            view.on('layoutChanged', select);
+            select();
+            return () => { view.off('layoutChanged', select); stop?.(); };
+        },
+    };
+}

package/native-environment.d.ts

@@ -0,0 +1,3 @@
+import type { View } from '@nativescript/core';
+import type { CssEnvironmentSource } from './css-environment';
+export declare function nativeCssEnvironmentSource(view: View): CssEnvironmentSource;

package/native-environment.ios.d.ts

@@ -0,0 +1,3 @@
+import type { View } from '@nativescript/core';
+import type { CssEnvironmentSource } from './css-environment';
+export declare function nativeCssEnvironmentSource(view: View): CssEnvironmentSource;

package/native-environment.ios.js

@@ -0,0 +1,65 @@
+const windows = new WeakMap();
+let ObserverClass;
+function observeWindow(window, changed) {
+    let observation = windows.get(window);
+    if (!observation) {
+        if (!ObserverClass) {
+            var SafeAreaObserver = (function (_super) {
+                __extends(SafeAreaObserver, _super);
+                function SafeAreaObserver() {
+                    return _super !== null && _super.apply(this, arguments) || this;
+                }
+                SafeAreaObserver.prototype.safeAreaInsetsDidChange = function () { var _a; _super.prototype.safeAreaInsetsDidChange.call(this); (_a = this.changed) === null || _a === void 0 ? void 0 : _a.call(this); };
+                SafeAreaObserver.prototype.layoutSubviews = function () { var _a; _super.prototype.layoutSubviews.call(this); (_a = this.changed) === null || _a === void 0 ? void 0 : _a.call(this); };
+                return SafeAreaObserver;
+            }(UIView));
+            ObserverClass = SafeAreaObserver;
+        }
+        const observer = ObserverClass.new();
+        const callbacks = new Set();
+        observation = { callbacks, observer };
+        windows.set(window, observation);
+        observer.frame = window.bounds;
+        observer.autoresizingMask = 2 /* UIViewAutoresizing.FlexibleWidth */ | 16 /* UIViewAutoresizing.FlexibleHeight */;
+        observer.userInteractionEnabled = false;
+        observer.isAccessibilityElement = false;
+        observer.changed = () => { for (const callback of Array.from(callbacks))
+            callback(); };
+        window.addSubview(observer);
+    }
+    observation.callbacks.add(changed);
+    const current = observation;
+    return () => {
+        current.callbacks.delete(changed);
+        if (!current.callbacks.size) {
+            current.observer.changed = undefined;
+            current.observer.removeFromSuperview();
+            windows.delete(window);
+        }
+    };
+}
+export function nativeCssEnvironmentSource(view) {
+    const windowOfView = () => view.nativeViewProtected?.window;
+    return {
+        read() {
+            const insets = windowOfView()?.safeAreaInsets;
+            return insets ? { top: insets.top, right: insets.right, bottom: insets.bottom, left: insets.left } : null;
+        },
+        subscribe(changed) {
+            let window;
+            let stop;
+            const select = () => {
+                const next = windowOfView();
+                if (next !== window) {
+                    stop?.();
+                    window = next;
+                    stop = next ? observeWindow(next, changed) : undefined;
+                }
+                changed();
+            };
+            view.on('layoutChanged', select);
+            select();
+            return () => { view.off('layoutChanged', select); stop?.(); };
+        },
+    };
+}

package/native-types-README.md

@@ -0,0 +1,51 @@
+# Independent Mason core bridge types
+
+The runtime and plugin prototypes ship their own Android/iOS bridge declarations.
+Their compiler inputs contain the standard NativeScript SDK types and core's
+generated declarations, without full MasonKit native types. This is type/build
+evidence; native ABI compatibility and application behavior have separate checks.
+
+## Regenerate after changing a native host
+
+Keep the generated `packages/nativescript-mason-core/typings/` files in Git so
+ordinary JavaScript builds do not require native build tools. To update them,
+first export both core native hosts and install the independent pinned SDK
+tooling. Neither consumer preparation nor a consumer app build is required. Run this
+target from the repository root under a native-build resource reservation:
+
+```sh
+pnpm exec nx run nativescript-mason-core:prepare.native.sdk
+pnpm exec nx run nativescript-mason-core:generate.native.types
+pnpm exec nx run nativescript-mason-core:verify.runtime
+pnpm exec nx run nativescript-mason-core:verify
+```
+
+Generation reads `MasonCore.aar` and the exported iOS Simulator framework directly.
+It preserves SDK header discovery so inherited UIKit members are included, then
+copies only MasonCore and its retained FontManager/SDWebImage declarations.
+The manifest records native artifact hashes, generator provenance and every
+declaration hash. Assembly rejects declarations for different native artifacts.
+Consumers still supply NativeScript's platform ambient types and `skipLibCheck`.
+
+## Android generator adaptation
+
+NativeScript Android 9.1.1's declaration generator produces invalid TypeScript
+for this core AAR: Kotlin parameter names can be invalid identifiers, ignored
+generic types can leave unmatched brackets, and nested class namespaces can
+have unmatched braces. Adding dependency JARs does not correct these syntax
+errors. These are declaration-generation findings, not Android runtime failures.
+
+The code-generation-only patch at
+`tools/mason-core/patches/android-dts-generator.patch` applies to
+[NativeScript/android-dts-generator at 5fcf6113](https://github.com/NativeScript/android-dts-generator/blob/5fcf611330bd9eb60d9bb45d5b37251980b127ab/dts-generator/src/main/java/com/telerik/dts/DtsApi.java).
+It makes invalid parameter names positional, balances ignored generic types,
+and emits complete nested namespace blocks. Generation verifies both the SDK
+JAR and original source hashes, compiles the adapted class in an ignored staging
+directory, and puts it before the unchanged SDK JAR on the generator classpath.
+It does not modify the installed SDK or ship generator code in the plugin.
+Review or remove this adaptation when adopting an upstream generator correction.
+
+Generated files are parsed before use. The packed consumer checks native host
+factories and rejects optional HTML APIs. Runtime compilation records its actual
+input files and rejects full MasonKit declarations. The build-only Windows facade
+is excluded from the archive; no Windows native host is qualified.