@nativescript/vite 8.0.0-alpha.6 → 8.0.0-alpha.61

package/hmr/server/core-bundle.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Single-eval @nativescript/core bundle for device serving (bundle mode).
+ *
+ * DEFAULT MODE (consumers)
+ * ------------------------
+ * Instead of serving @nativescript/core per-module through Vite's transform
+ * pipeline (~hundreds of serial HTTP fetches + per-file transforms during cold
+ * boot), the dev server pre-bundles the ENTIRE core package with esbuild into
+ * one ESM payload served at `GET /ns/core-bundle.mjs`. The canonical
+ * `/ns/core[/<sub>]` URL space is preserved — those routes serve THIN SHIMS
+ * that statically import the bundle and re-export the requested subpath's
+ * namespace from the `globalThis.__NS_CORE_MODULES__` registry the bundle
+ * populates. Because every shim's only dependency is the one bundle URL,
+ * V8/iOS evaluates core exactly once per app lifetime — the single-realm
+ * invariant is enforced by construction, with ONE big prefetchable payload
+ * instead of a deep serial fetch chain.
+ *
+ * OPT-IN PER-MODULE MODE (core maintainers)
+ * -----------------------------------------
+ * Set `NS_CORE_PER_MODULE=1` to keep the classic per-module `/ns/core` bridge
+ * (websocket-ns-core.ts). That is the right mode when editing
+ * `@nativescript/core` source live inside the NativeScript monorepo: each core
+ * module stays individually served/transformed so core edits participate in
+ * HMR. Consumers of the published package don't edit core mid-session, so the
+ * bundle is both safe and much faster for them.
+ *
+ * FAILURE FALLBACK
+ * ----------------
+ * If the esbuild bundle build fails for any reason, the service marks itself
+ * failed and `/ns/core[/<sub>]` transparently falls back to the per-module
+ * bridge for the whole session (logged loudly once). Boot still works; only
+ * the speed win is lost.
+ */
+import type { ViteDevServer } from 'vite';
+import type { Platform } from '../../helpers/platform-types.js';
+/**
+ * Per-module /ns/core serving mode (vs the default single-eval bundle).
+ *
+ * `NS_CORE_PER_MODULE=1|true` forces it on, `0|false` forces bundle mode.
+ * When unset, it AUTO-ENABLES for monorepo core source (packages/core in the
+ * NativeScript repo). Two reasons:
+ *   - core maintainers edit core live, and per-module serving keeps those
+ *     edits in HMR;
+ *   - realm safety: the build-time externalizer emits
+ *     `/ns/m/packages/core/<file>` URLs for workspace-source core (see the
+ *     `ns-core-external-urls` workspace branch in configuration/base.ts), so
+ *     the served graph's core realm lives under /ns/m. A bundle-mode
+ *     `/ns/core-bundle.mjs` would evaluate a complete SECOND copy of core for
+ *     the entry's `/ns/core/globals|application|…` imports — duplicate native
+ *     class registrations crash in MetadataBuilder at startup.
+ */
+export declare function isCorePerModuleServingEnabled(env?: NodeJS.ProcessEnv, hasWorkspaceCoreSource?: () => boolean): boolean;
+export interface CoreBundleState {
+    /** Full ESM payload served at /ns/core-bundle.mjs (shape header + esbuild output). */
+    code: string;
+    /** Canonical subpaths registered in the bundle's __NS_CORE_MODULES__ registry. */
+    subs: Set<string>;
+    hash: string;
+    builtAt: number;
+    buildMs: number;
+}
+export interface CoreBundleService {
+    /** Resolves the built bundle, or null when the build failed (per-module fallback). */
+    ensureBuilt(): Promise<CoreBundleState | null>;
+    /** Synchronous view — null until built (or when failed). */
+    getState(): CoreBundleState | null;
+    hasFailed(): boolean;
+}
+export interface GenerateCoreBundleOptions {
+    projectRoot: string;
+    platform: Platform | string;
+    mode: 'development' | 'production' | string;
+    flavor?: string;
+    verbose?: boolean;
+}
+/**
+ * Resolve the physical @nativescript/core root the same way configuration/
+ * base.ts does: prefer monorepo source (`<workspace>/packages/core`), else the
+ * node_modules install reachable from the project root.
+ */
+export declare function resolveCoreRootForBundle(projectRoot: string): string;
+/**
+ * True when a canonical core subpath was DELIBERATELY excluded from bundle
+ * enumeration (debugger/, inspector_modules, bundle-entry-points, …). Requests
+ * for these at boot are normal — the runtime's inspector/debugger plumbing
+ * imports them in dev — and the per-module fallback that serves them is
+ * by-design and realm-safe. Callers use this to keep the fallback log
+ * verbose-only for expected subs while still surfacing unexpected
+ * enumeration misses.
+ */
+export declare function isExpectedCoreBundleExclusion(canonicalSub: string): boolean;
+/**
+ * Enumerate every importable core subpath (canonical form, per
+ * `normalizeCoreSub`) for the given platform. A subpath is included when it
+ * has a platform-neutral variant OR a variant for the current platform —
+ * other-platform-only modules (e.g. `ui/frame/activity.android` on iOS) are
+ * skipped since they can never resolve for this build.
+ */
+export declare function enumerateCoreModuleSubpaths(coreRoot: string, platform: string): string[];
+/**
+ * Synthetic esbuild entry: evaluate core once, expose every subpath's live
+ * namespace through `globalThis.__NS_CORE_MODULES__` (the SAME registry the
+ * per-module bridge footers populate, so the vendor CJS `require()` shim and
+ * `_nsReq` lookups keep working unchanged), and re-export the package main so
+ * `/ns/core-bundle.mjs` itself has core's full named-export surface.
+ */
+export declare function buildCoreBundleEntryCode(subs: readonly string[]): string;
+export declare function computeCoreBundleCacheKey(input: {
+    coreRoot: string;
+    coreVersion: string;
+    corePkgMtimeMs: number;
+    platform: string;
+    mode: string;
+    flavor: string;
+    defines: Record<string, string>;
+    nsConfigJson: string;
+    subs: readonly string[];
+    vitePackageVersion: string;
+}): string;
+export declare function tryLoadCoreBundleFromDisk(projectRoot: string, platform: string, key: string): CoreBundleState | null;
+export declare function saveCoreBundleToDisk(projectRoot: string, platform: string, key: string, state: CoreBundleState, verbose?: boolean): void;
+export declare function generateCoreBundle(options: GenerateCoreBundleOptions): Promise<CoreBundleState>;
+export declare function createCoreBundleService(options: GenerateCoreBundleOptions): CoreBundleService;
+/**
+ * Process-wide bundle service derived from the dev server's config + CLI
+ * flags. One dev server per process, so a module-level singleton matches the
+ * vendor manifest's lifecycle.
+ */
+export declare function getSharedCoreBundleService(server: ViteDevServer): CoreBundleService;
+/** Test seam: drop the shared service so specs can mount fresh. */
+export declare function resetSharedCoreBundleServiceForTests(): void;
+export declare const CORE_BUNDLE_PATH = "/ns/core-bundle.mjs";
+/**
+ * Shim served at `/ns/core` in bundle mode. `export * from` gives real,
+ * live named bindings straight off the bundle module record; the explicit
+ * default keeps the "default import + destructure" consumer rewrite working
+ * (see buildDefaultExportFooter in ns-core-cjs-shape.ts for that contract).
+ */
+export declare function buildCoreMainShimCode(): string;
+export declare function buildCoreSubShimCode(sub: string, exportNames: readonly string[], hasOwnDefaultExport?: boolean): string;