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

package/plugin-README.md

@@ -0,0 +1,234 @@
+# Mason core NativeScript plugin proof
+
+This experimental plugin combines the container-only JavaScript runtime with the
+independently built native hosts. It excludes MasonKit's HTML parser, rich-text
+renderer and optional widgets. The portable helper proof and existing full MasonKit package remain separate.
+The normal core build produces this plugin.
+
+Build the hosts, then assemble the plugin:
+
+```sh
+pnpm exec nx run nativescript-mason-core:verify.host.ios.artifact
+pnpm exec nx run nativescript-mason-core:verify.host.ios.device.artifact
+pnpm exec nx run nativescript-mason-core:build.host.ios.xcframework
+pnpm exec nx run nativescript-mason-core:build.host.android
+pnpm exec nx run nativescript-mason-core:build
+```
+
+Native builds require the development environment's native-build resource
+reservation. Assembly reads the exported artifacts and verifies their hashes;
+it does not rebuild them. The result is
+`dist/packages/nativescript-mason-core`.
+
+Verify its packed files and prepare the isolated NativeScript app:
+
+```sh
+pnpm exec nx run nativescript-mason-core:prepare.consumer
+cd tmp/mason-core-nativescript-consumer
+pnpm install
+```
+
+The fixture has its own pnpm workspace and explicit build-script allowlist.
+Do not pass `--ignore-workspace`: that also ignores this fixture's dependency
+policy. After regenerating the tarball, use `pnpm install --force` to refresh
+the installed file dependency. Run the native build targets from the repository
+root under a native-build reservation:
+
+```sh
+pnpm exec nx run nativescript-mason-core:build.consumer.ios
+pnpm exec nx run nativescript-mason-core:build.consumer.android
+```
+
+The app creates Mason containers hosting ordinary NativeScript labels and
+writes geometry/ownership assertions to its documents folder as
+`mason-core-result.json`. Build success alone does not establish that they pass.
+The package includes independent native bridge declarations, generated from
+the core artifacts. Assembly rejects types whose recorded native hashes differ
+from the hosts being packaged. See [native type generation](native-types-README.md).
+
+Run the application assertions from the repository root:
+
+```sh
+pnpm exec nx run nativescript-mason-core:test.consumer.ios
+pnpm exec nx run nativescript-mason-core:test.consumer.android.device
+```
+
+The iOS runner uses the dedicated simulator recorded by the native host test
+setup. The Android runner uses the sole authorized arm64 phone, or
+`MASON_CORE_ANDROID_SERIAL` when several are connected. Reserve the corresponding
+device before running. Each runner stops its own probe afterward; the Android
+runner verifies ownership before replacing an installed app.
+
+The prototype includes an arm64 iOS device/simulator XCFramework and an Android
+arm64-v8a AAR. Release-size savings remain unqualified.
+The isolated apps pass bridge, native geometry and ownership assertions on an
+arm64 iOS simulator and an API 36 Android phone. They install only core and
+NativeScript core as runtime dependencies. The iOS app declares the scene
+lifecycle required by the current SDK; NativeScript provides its default scene
+delegate. Plain-app assertions and renderer assertions are qualified separately.
+The compiled scenario also passes OS input on the simulator and Android emulator
+as described below. Do not switch production consumers or publish
+this artifact.
+
+iOS retains embedded FontManager and SDWebImage code, dependency module headers,
+licenses and the SDWebImage resource/privacy bundle embedded in each matching
+framework slice. Android declares the same
+direct Maven dependencies as the native host build; their transitive AndroidX
+cost remains. No app-size savings have been measured.
+
+Use core and full MasonKit in separate apps. Native Objective-C/JNI class names
+are deliberately preserved, so coinstallation is unsupported. The package's
+`artifact-inventory.json` records every shipped file's SHA-256 hash. Platform
+manifests preserve native build provenance.
+
+## Qualify the Xplat renderer separately
+
+The renderer scenario reads the selected Xplat checkout's catalog pins and
+canonical Octane, NativeScript core and renderer patches. It changes only the
+renderer patch's two Mason package imports to point at core. It records patch
+hashes and the Xplat commit, verifies shared runtime resolution, and rejects
+full MasonKit anywhere in the installed production graph.
+
+```sh
+MASON_CORE_XPLAT_REPOSITORY=/path/to/octane-xplat \
+  pnpm exec nx run nativescript-mason-core:prepare.consumer.renderer
+cd tmp/mason-core-nativescript-consumer
+pnpm install --force
+```
+
+Return to the repository root and use the same build and consumer test targets
+shown above. The scenario checks driver geometry updates, reparenting and
+disposal, followed by a real Octane component mount/update/unmount. Its checks
+are a separate qualification from the plain application's bridge assertions;
+a successful build does not establish a renderer runtime pass.
+
+The renderer scenario passes on an arm64 iOS 27 simulator and API 35 arm64
+Android emulator with Octane 0.14.0, renderer 0.2.5 and NativeScript core 9.1.3.
+It includes native geometry after prop updates, reparenting/disposal and an
+Octane component mount/update/unmount without recreating its foreign label.
+The same-dependency plain controls pass on both targets. These results do not
+qualify compiled TSRX components, hook subscriptions, OS input or a physical
+Android renderer run. The earlier plain-app phone result remains separate.
+
+The `prepare.consumer.renderer.control` target uses the same dependency pins
+and patches with the plain NativeScript entry instead. It isolates SDK changes
+from renderer operations. Reinstall and rebuild after changing scenarios. The
+builder regenerates only its owned platform directory when native dependency
+inputs change, avoiding stale Xcode references to previous pnpm peer paths.
+
+When no phone is connected, reserve the dedicated `android:mason-core-extraction`
+AVD and one resident-device slot, then run:
+
+```sh
+pnpm exec nx run nativescript-mason-core:test.consumer.android.emulator
+```
+
+The emulator runner boots and shuts down only that owned AVD. Emulator results
+remain distinct from physical-device results. These checks do not exercise OS
+touch input or establish release-size savings.
+
+## Compile TSRX and verify hooks
+
+The compiled scenario uses the same renderer dependency boundary, with an
+authored component under `src/*.tsrx`. Prepare it with the selected Xplat
+checkout, then install, build and run using the commands above:
+
+```sh
+MASON_CORE_XPLAT_REPOSITORY=/path/to/octane-xplat \
+  pnpm exec nx run nativescript-mason-core:prepare.consumer.compiled
+```
+
+The native build invokes the pinned Octane 0.14.0 compiler before webpack.
+Its optional `@tsrx/oxc` 0.20.0 parser belongs to this fixture's development
+dependencies; core gains no dependency. The emitted hooks import the native
+renderer runtime, and `compiled-component-manifest.json` records source and
+emission hashes. The component runs in the same Page/Frame hosting pattern
+as Xplat's mobile application.
+
+This scenario passes on arm64 iOS 27 Simulator and the API 35 Android emulator.
+It checks class-authored geometry, a synthesized NativeScript button handler,
+hook-driven text/size updates without replacing the label, scroll content and
+programmatic seek, effect cleanup, ref clearing and host release. The button
+notification is explicitly synthetic; these results do not establish OS touch
+input or physical-device renderer qualification.
+
+## Verify OS taps and touch scrolling
+
+Build the compiled scenario above, then run these targets under the matching
+owned-device reservation:
+
+```sh
+pnpm exec nx run nativescript-mason-core:test.consumer.ios.input
+pnpm exec nx run nativescript-mason-core:test.consumer.android.input.emulator
+```
+
+The iOS target requires `idb` and `idb_companion` on `PATH`. It creates a private
+companion socket for the owned simulator and sends HID coordinate input. The
+Android target uses `adb shell input` after confirming that the owned app has
+focus. For a connected authorized phone, use
+`test.consumer.android.input.device` instead. No screenshots are required.
+
+The app reports native button and scroll coordinates in
+`mason-core-input-ready.json`; the runner records each delivered phase in
+`input-actions.json`. In this mode the app waits for a real tap and swipe. It
+requires the count and label width to update, then checks that an on-screen
+row moves by the reported scroll offset before verifying effect/ref cleanup.
+The ordinary consumer targets retain synthetic notification and programmatic
+seek coverage. Input results must be reported separately from those checks
+and separately for simulators, emulators and physical devices.
+
+OS-input checks pass on arm64 iOS 27 Simulator and the API 35 Android emulator.
+Native row movement matches the reported scroll offset (137.3 points on iOS,
+94.9 logical pixels on Android). The actual-Vite consumer also passes on the
+API 36 physical Android phone
+with registry core `1.0.0-beta.0` and current Xplat patches: a real inspector
+WebSocket responds, an OS tap changes the hook-driven label width from about
+90 to 130, and an OS swipe moves its native row by the reported 99.38 logical
+pixels before cleanup. Run the prepared fixture with:
+
+```sh
+MASON_CORE_ANDROID_SERIAL=DEVICE_SERIAL pnpm exec nx run \
+  nativescript-mason-core:test.consumer.android.input.device --inspector
+```
+
+Replace `DEVICE_SERIAL` with the authorized physical phone's adb serial.
+The published beta also passes the actual-Vite fixture on arm64 iOS 27
+Simulator: native HID tap changes width from 90 to 130 points, swipe produces
+matching native row movement and scroll offset (169.29 points), and cleanup
+runs once. With the dedicated simulator shut down and its resource reservation
+held, run:
+
+```sh
+pnpm exec nx run nativescript-mason-core:build.consumer.ios
+pnpm exec nx run nativescript-mason-core:test.consumer.ios.input
+```
+
+iOS physical runtime and input remain unqualified. The signed development app
+and a native UI-test runner build successfully. A temporary device test
+passes its tap/count checks, but fails its final post-drag assertion; it has
+not produced a passing consumer result. This does not resolve the separate
+intermittent Android emulator cold-start failures.
+
+## Build an unsigned iOS device app
+
+The same installed compiled consumer can build a device application without
+selecting certificates or changing provisioning:
+
+```sh
+pnpm exec nx run nativescript-mason-core:build.consumer.ios.device
+```
+
+This target prepares through NativeScript, then invokes Xcode with signing
+disabled. It checks that the app selects the device framework, embeds the
+device privacy bundle and generates the core bridge classes without optional
+HTML/text/widget declarations. This is build/metadata evidence only; no iOS
+physical-device runtime or distribution signing is qualified.
+
+
+## Safe-area environment resolver
+
+Core `1.0.0-beta.1` automatically binds loaded Mason roots to their owning
+native window when a subtree first uses `env()`. See the package README for
+window ownership, explicit source overrides, fallback semantics and headless
+coverage. Actual native inset dispatch/layout remains unqualified; Xplat keeps
+a qualification warning for this beta.

package/properties.d.ts

@@ -0,0 +1,154 @@
+import { CssProperty, CssAnimationProperty, InheritedCssProperty, Style, ShorthandProperty, Property } from '@nativescript/core';
+import { Display, Overflow, Length, Gap, LengthAuto, Position, BoxSizing, GridAutoFlow, AlignContent, VerticalAlign, Float, Clear } from '.';
+import type { ViewBase } from './common';
+import type { LonghandValue } from './css-shorthands';
+type ShorthandLonghand = CssProperty<Style, any> | CssAnimationProperty<Style, any>;
+export interface MasonShorthand {
+    cssName: string;
+    longhands: ShorthandLonghand[];
+    split(value: string): LonghandValue[];
+}
+export declare function shorthandConverter({ cssName, longhands, split }: MasonShorthand): (value: unknown) => [ShorthandLonghand, unknown][];
+export declare const textProperty: Property<ViewBase, string>;
+export declare const displayProperty: CssProperty<Style, Display>;
+export declare const filterProperty: CssProperty<Style, string>;
+export declare const borderColorProperty: CssProperty<Style, string>;
+export declare const backgroundProperty: CssProperty<Style, string>;
+export declare const backgroundImageProperty: CssProperty<Style, string>;
+export declare const backgroundRepeatProperty: CssProperty<Style, string>;
+export declare const backgroundPositionProperty: CssProperty<Style, string>;
+export declare const backgroundSizeProperty: CssProperty<Style, string>;
+export declare const backgroundClipProperty: CssProperty<Style, string>;
+export declare const overflowXProperty: CssProperty<Style, Overflow>;
+export declare const overflowYProperty: CssProperty<Style, Overflow>;
+export declare const overflowProperty: ShorthandProperty<Style, any>;
+export declare const paddingProperty: CssProperty<Style, string>;
+export declare const whiteSpaceProperty: CssProperty<Style, string>;
+/**
+ * CSS `touch-action` as the pan flags native scroll views read: 1 = pan-x,
+ * 2 = pan-y, 4 = pinch-zoom. A Mason scroll view only starts a drag along an
+ * axis every element from the touched one up to it allows, as browsers do.
+ */
+export declare function parseTouchAction(value: string): number;
+export declare const touchActionProperty: CssProperty<Style, string>;
+export declare const objectFitProperty: CssProperty<Style, string>;
+export declare const textJustifyProperty: CssProperty<Style, string>;
+export declare const backgroundPositionXProperty: CssProperty<Style, string>;
+export declare const backgroundPositionYProperty: CssProperty<Style, string>;
+export declare const backgroundOriginProperty: CssProperty<Style, string>;
+export declare const backgroundAttachmentProperty: CssProperty<Style, string>;
+export declare const backgroundBlendModeProperty: CssProperty<Style, string>;
+export declare const textDecorationLineProperty: CssProperty<Style, string>;
+export declare const textDecorationStyleProperty: CssProperty<Style, string>;
+export declare const textDecorationColorProperty: CssProperty<Style, string>;
+export declare const textDecorationThicknessProperty: CssProperty<Style, string>;
+export declare const fontFamilyProperty: CssProperty<Style, string>;
+export declare const marginProperty: CssProperty<Style, string>;
+export declare const scrollBarWidthProperty: CssProperty<Style, number>;
+/** The declaration behind `value` if it came from this view's own CSS, else `value`. */
+export declare function masonRawDeclaration(style: Style, propertyName: string, value: unknown): unknown;
+export declare const rowGapProperty: CssProperty<Style, Length>;
+export declare const columnGapProperty: CssProperty<Style, Length>;
+export declare const gridGapProperty: ShorthandProperty<Style, any>;
+export declare const gapProperty: ShorthandProperty<Style, any>;
+export declare const gridRowGapProperty: ShorthandProperty<Style, Gap>;
+export declare const gridColumnGapProperty: ShorthandProperty<Style, Length>;
+export declare const maxWidthProperty: CssProperty<Style, LengthAuto>;
+export declare const maxHeightProperty: CssProperty<Style, LengthAuto>;
+export declare function installMasonSizeUnits(style: Style): void;
+export declare const insetProperty: ShorthandProperty<Style, LengthAuto>;
+export declare const leftProperty: CssProperty<Style, LengthAuto>;
+export declare const rightProperty: CssProperty<Style, LengthAuto>;
+export declare const topProperty: CssProperty<Style, LengthAuto>;
+export declare const bottomProperty: CssProperty<Style, LengthAuto>;
+export declare const positionProperty: CssProperty<Style, Position>;
+export declare const boxSizingProperty: CssProperty<Style, BoxSizing>;
+export declare const borderRadiusProperty: CssProperty<Style, string>;
+export declare const AlignItemsIsValid: (value: any) => value is string;
+export declare const AlignItemsParse: (value: any) => unknown;
+export declare const AlignSelfIsValid: (value: any) => value is string;
+export declare const AlignSelfParse: (value: any) => unknown;
+export declare const AlignContentIsValid: (value: any) => value is string;
+export declare const AlignContentParse: (value: any) => unknown;
+export declare const alignContentProperty: CssProperty<Style, AlignContent>;
+export declare const justifyItemsProperty: CssProperty<Style, import("./layout-types").AlignItems>;
+export declare const justifySelfProperty: CssProperty<Style, import("./layout-types").AlignSelf>;
+export declare const placeShorthands: MasonShorthand[];
+export declare const JustifyContentIsValid: (value: any) => value is string;
+export declare const JustifyContentParse: (value: any) => unknown;
+export declare const flexBasisProperty: CssProperty<Style, LengthAuto>;
+export declare const aspectRatioProperty: CssProperty<Style, number>;
+export declare const gridAutoRowsProperty: CssProperty<Style, string>;
+export declare const gridAutoColumnsProperty: CssProperty<Style, string>;
+export declare const gridAutoFlowProperty: CssProperty<Style, GridAutoFlow>;
+export declare const gridAreaProperty: CssProperty<Style, string>;
+export declare const gridColumnStartProperty: CssProperty<Style, string>;
+export declare const gridColumnEndProperty: CssProperty<Style, string>;
+export declare const gridColumnProperty: CssProperty<Style, string>;
+export declare const gridRowStartProperty: CssProperty<Style, string>;
+export declare const gridRowEndProperty: CssProperty<Style, string>;
+export declare const gridRowProperty: CssProperty<Style, string>;
+export declare const gridTemplateAreasProperty: CssProperty<Style, string>;
+export declare const gridTemplateRowsProperty: CssProperty<Style, string>;
+export declare const gridTemplateColumnsProperty: CssProperty<Style, string>;
+export declare const textWrapProperty: CssProperty<Style, "nowrap" | "wrap" | "balance">;
+export declare const textOverFlowProperty: CssProperty<Style, string>;
+export declare const verticalAlignProperty: CssProperty<Style, VerticalAlign>;
+export declare const floatProperty: CssProperty<Style, Float>;
+export declare const clearProperty: CssProperty<Style, Clear>;
+export declare const cornerShapeProperty: CssProperty<Style, string>;
+export declare const boxShadowProperty: CssProperty<Style, string>;
+export declare const transformProperty: CssProperty<Style, string>;
+export declare const cornerShapeTopLeftProperty: CssProperty<Style, string>;
+export declare const cornerShapeTopRightProperty: CssProperty<Style, string>;
+export declare const cornerShapeBottomRightProperty: CssProperty<Style, string>;
+export declare const cornerShapeBottomLeftProperty: CssProperty<Style, string>;
+/** Splits `a / b / ...` into `count` longhands, filling omitted ones as CSS Grid does. */
+export declare function gridParts(value: string, count: number): string[];
+export declare const objectPositionProperty: CssProperty<Style, string>;
+export declare const borderTopStyleProperty: CssProperty<Style, string>;
+export declare const borderRightStyleProperty: CssProperty<Style, string>;
+export declare const borderBottomStyleProperty: CssProperty<Style, string>;
+export declare const borderLeftStyleProperty: CssProperty<Style, string>;
+export declare const borderImageProperty: CssProperty<Style, string>;
+export declare const fontStretchProperty: CssProperty<Style, string>;
+export declare const fontFeatureSettingsProperty: CssProperty<Style, string>;
+export declare const wordSpacingProperty: CssProperty<Style, string>;
+export declare const hyphensProperty: CssProperty<Style, string>;
+export declare const textIndentProperty: CssProperty<Style, string>;
+export declare const lineClampProperty: CssProperty<Style, string>;
+export declare const webkitLineClampProperty: CssProperty<Style, string>;
+export declare const transformOriginProperty: CssProperty<Style, string>;
+export declare const backdropFilterProperty: CssProperty<Style, string>;
+export declare const maskImageProperty: CssProperty<Style, string>;
+export declare const maskSizeProperty: CssAnimationProperty<Style, string>;
+export declare const maskPositionProperty: CssAnimationProperty<Style, string>;
+export declare const maskRepeatProperty: CssProperty<Style, string>;
+export declare const maskOriginProperty: CssProperty<Style, string>;
+export declare const maskClipProperty: CssProperty<Style, string>;
+export declare const maskModeProperty: CssProperty<Style, string>;
+export declare const maskCompositeProperty: CssProperty<Style, string>;
+export declare const clipPathProperty: CssProperty<Style, string>;
+export declare const maskBorderSourceProperty: CssProperty<Style, string>;
+export declare const maskBorderSliceProperty: CssProperty<Style, string>;
+export declare const maskBorderWidthProperty: CssProperty<Style, string>;
+export declare const maskBorderOutsetProperty: CssProperty<Style, string>;
+export declare const maskBorderRepeatProperty: CssProperty<Style, string>;
+export declare const maskBorderModeProperty: CssProperty<Style, string>;
+export declare const maskProperty: ShorthandProperty<Style, any>;
+export declare const maskBorderProperty: ShorthandProperty<Style, any>;
+export declare const writingModeProperty: CssProperty<Style, string>;
+export declare const unicodeBidiProperty: CssProperty<Style, string>;
+export declare const caretColorProperty: CssProperty<Style, string>;
+export declare const listStyleTypeProperty: InheritedCssProperty<Style, string>;
+export declare const listStylePositionProperty: InheritedCssProperty<Style, string>;
+export declare const listStyleShorthand: MasonShorthand;
+export declare const listStyleProperty: ShorthandProperty<Style, any>;
+export declare const borderStyleProperty: ShorthandProperty<Style, any>;
+export declare const borderProperty: ShorthandProperty<Style, any>;
+export declare const borderTopProperty: ShorthandProperty<Style, any>;
+export declare const borderRightProperty: ShorthandProperty<Style, any>;
+export declare const borderBottomProperty: ShorthandProperty<Style, any>;
+export declare const borderLeftProperty: ShorthandProperty<Style, any>;
+export declare const masonShorthands: MasonShorthand[];
+export {};