@nativescript/vite 8.0.0-alpha.9 → 8.0.0-dev.0

package/configuration/angular.js

@@ -1,139 +1,72 @@
 import { mergeConfig } from 'vite';
 import path from 'path';
 import fs from 'node:fs';
-import { createRequire } from 'node:module';
 import angular from '@analogjs/vite-plugin-angular';
-import { angularLinkerVitePlugin, angularLinkerVitePluginPost } from '../helpers/angular/angular-linker.js';
-import { synthesizeMissingInjectableFactories } from '../helpers/angular/synthesize-injectable-factories.js';
-import { ensureSharedAngularLinker, resolveAngularFileSystem } from '../helpers/angular/shared-linker.js';
-import { inlineDecoratorComponentTemplates } from '../helpers/angular/inline-decorator-component-templates.js';
-import { appendComponentHmrRegistration, findComponentClassNames, INJECTION_MARKER as HMR_REGISTER_MARKER } from '../helpers/angular/inject-component-hmr-registration.js';
-import { synthesizeDecoratorCtorParameters } from '../helpers/angular/synthesize-decorator-ctor-parameters.js';
-import { containsRealNgDeclare, stripJsComments } from '../helpers/angular/util.js';
+import { angularLinkerVitePlugin, angularLinkerVitePluginPost } from '../hmr/frameworks/angular/build/angular-linker.js';
+import { synthesizeMissingInjectableFactories } from '../hmr/frameworks/angular/build/synthesize-injectable-factories.js';
+import { getAngularLinkerFactory, runAngularLinker } from '../hmr/frameworks/angular/build/shared-linker.js';
+import { recordLinkerHit, reportLinkerLayerStats } from '../hmr/frameworks/angular/build/linker-stats.js';
+import { inlineDecoratorComponentTemplates } from '../hmr/frameworks/angular/build/inline-decorator-component-templates.js';
+import { appendComponentHmrRegistration, findComponentClassNames, INJECTION_MARKER as HMR_REGISTER_MARKER } from '../hmr/frameworks/angular/build/inject-component-hmr-registration.js';
+import { injectAngularHmrViteIgnore } from '../hmr/frameworks/angular/build/inject-hmr-vite-ignore.js';
+import { synthesizeDecoratorCtorParameters } from '../hmr/frameworks/angular/build/synthesize-decorator-ctor-parameters.js';
+import { containsRealNgDeclare, stripJsComments } from '../hmr/frameworks/angular/build/util.js';
 import { baseConfig } from './base.js';
 import { getCliFlags } from '../helpers/cli-flags.js';
+import { getMonorepoWorkspaceRoot } from '../helpers/project.js';
 import { resolveRelativeToImportMeta } from '../helpers/import-meta-path.js';
 import { resolveVerboseFlag } from '../helpers/logging.js';
-// Lazily import the Angular linker factory function. Used by chunk-level linkers
-// to create FRESH plugin instances per invocation (avoiding stale state in watch mode).
-let _cachedLinkerFactory = null;
-async function importLinkerFactory() {
-    if (_cachedLinkerFactory)
-        return _cachedLinkerFactory;
-    const req = createRequire(process.cwd() + '/package.json');
-    try {
-        const linkerPath = req.resolve('@angular/compiler-cli/linker/babel');
-        const linkerMod = await import(linkerPath);
-        _cachedLinkerFactory = linkerMod.createLinkerPlugin || linkerMod.createEs2015LinkerPlugin || null;
-    }
-    catch {
-        try {
-            const linkerMod = await import('@angular/compiler-cli/linker/babel');
-            _cachedLinkerFactory = linkerMod.createLinkerPlugin || linkerMod.createEs2015LinkerPlugin || null;
-        }
-        catch { }
-    }
-    return _cachedLinkerFactory;
+import { NS_OPTIMIZE_DEPS_EXCLUDE } from '../helpers/optimize-deps.js';
+function hasNgDeclarePartial(code) {
+    return code.indexOf('\u0275\u0275ngDeclare') !== -1 || code.indexOf('ɵɵngDeclare') !== -1 || code.indexOf('ngDeclare') !== -1;
 }
 // Rollup-level linker to guarantee Angular libraries are linked when included in the bundle graph.
 function angularRollupLinker(projectRoot) {
-    let babel = null;
-    let createLinker = null;
-    let angularFileSystem = null;
     const FILTER = /node_modules\/(?:@angular|@nativescript\/angular)\/.*\.[mc]?js$/;
-    async function ensureDeps() {
-        if (babel && createLinker)
-            return;
-        try {
-            const req = createRequire((projectRoot ? projectRoot + '/package.json' : import.meta.url));
-            const babelPath = req.resolve('@babel/core');
-            const linkerPath = req.resolve('@angular/compiler-cli/linker/babel');
-            babel = await import(babelPath);
-            const linkerMod = await import(linkerPath);
-            createLinker = linkerMod.createLinkerPlugin || linkerMod.createEs2015LinkerPlugin;
-        }
-        catch {
-            try {
-                babel = await import('@babel/core');
-            }
-            catch { }
-            try {
-                const linkerMod = await import('@angular/compiler-cli/linker/babel');
-                createLinker = linkerMod.createLinkerPlugin || linkerMod.createEs2015LinkerPlugin;
-            }
-            catch { }
-        }
-        if (!angularFileSystem) {
-            angularFileSystem = await resolveAngularFileSystem(projectRoot);
-        }
-    }
+    const debug = process.env.VITE_DEBUG_LOGS === 'true' || process.env.VITE_DEBUG_LOGS === '1';
     return {
         name: 'ns-angular-linker-rollup',
         enforce: 'pre',
         apply: 'build',
         async load(id) {
-            const debug = process.env.VITE_DEBUG_LOGS === 'true' || process.env.VITE_DEBUG_LOGS === '1';
-            const cleanId = id.split('?', 1)[0];
+            const cleanId = normalizeAngularWatchPath(id);
             if (!FILTER.test(cleanId))
                 return null;
             try {
-                await ensureDeps();
-                if (!babel || !createLinker)
-                    return null;
                 const fs = await import('node:fs/promises');
                 const code = await fs.readFile(cleanId, 'utf8');
                 const forceLink = cleanId.includes('/node_modules/@nativescript/angular/') && cleanId.includes('polyfills');
                 if (!code)
                     return null;
-                if (!forceLink && code.indexOf('\u0275\u0275ngDeclare') === -1 && code.indexOf('ɵɵngDeclare') === -1 && code.indexOf('ngDeclare') === -1)
+                if (!forceLink && !hasNgDeclarePartial(code))
                     return null;
-                const plugin = createLinker({ sourceMapping: false, fileSystem: angularFileSystem });
-                if (debug) {
-                    console.log('[ns-angular-linker][rollup-load] linking', cleanId);
-                }
-                const result = await babel.transformAsync(code, {
-                    filename: cleanId,
-                    configFile: false,
-                    babelrc: false,
-                    sourceMaps: false,
-                    compact: false,
-                    plugins: [plugin],
-                });
-                if (result?.code && result.code !== code) {
-                    return { code: result.code, map: null };
+                const linked = await runAngularLinker(code, { filename: cleanId, projectRoot, freshPlugin: true });
+                if (linked) {
+                    recordLinkerHit('rollup-load');
+                    if (debug)
+                        console.log('[ns-angular-linker][rollup-load] linked', cleanId);
+                    return { code: linked, map: null };
                 }
             }
             catch { }
             return null;
         },
         async transform(code, id) {
-            const debug = process.env.VITE_DEBUG_LOGS === 'true' || process.env.VITE_DEBUG_LOGS === '1';
-            const cleanId = id.split('?', 1)[0];
+            const cleanId = normalizeAngularWatchPath(id);
             if (!FILTER.test(cleanId))
                 return null;
             const forceLink = cleanId.includes('/node_modules/@nativescript/angular/') && cleanId.includes('polyfills');
             if (!code)
                 return null;
-            if (!forceLink && code.indexOf('\u0275\u0275ngDeclare') === -1 && code.indexOf('ɵɵngDeclare') === -1 && code.indexOf('ngDeclare') === -1)
-                return null;
-            await ensureDeps();
-            if (!babel || !createLinker)
+            if (!forceLink && !hasNgDeclarePartial(code))
                 return null;
             try {
-                const plugin = createLinker({ sourceMapping: false, fileSystem: angularFileSystem });
-                if (debug) {
-                    console.log('[ns-angular-linker][rollup] linking', cleanId);
-                }
-                const result = await babel.transformAsync(code, {
-                    filename: cleanId,
-                    configFile: false,
-                    babelrc: false,
-                    sourceMaps: false,
-                    compact: false,
-                    plugins: [plugin],
-                });
-                if (result?.code && result.code !== code) {
-                    return { code: result.code, map: null };
+                const linked = await runAngularLinker(code, { filename: cleanId, projectRoot, freshPlugin: true });
+                if (linked) {
+                    recordLinkerHit('rollup');
+                    if (debug)
+                        console.log('[ns-angular-linker][rollup] linked', cleanId);
+                    return { code: linked, map: null };
                 }
             }
             catch { }
@@ -144,6 +77,24 @@ function angularRollupLinker(projectRoot) {
 const cliFlags = getCliFlags();
 const isDevEnv = process.env.NODE_ENV !== 'production';
 const hmrActive = isDevEnv && !!cliFlags.hmr;
+/**
+ * Web-style template HMR opt-out (`NS_VITE_ANGULAR_LIVE_RELOAD=0`).
+ *
+ * With HMR active we default to the in-place template-replacement pipeline
+ * (see the `liveReload` option below). If a project hits a regression
+ * (broken styling, unresolved `?ngcomp=` imports), this env flag rolls back
+ * to the legacy reboot pipeline without an upstream patch. `0`, `false`,
+ * `off`, and `no` (case-insensitive) mean "off"; anything else — including
+ * unset — keeps the new path on. Read once at module load, like `hmrActive`.
+ */
+const angularLiveReloadDisabledByEnv = (() => {
+    const raw = process.env.NS_VITE_ANGULAR_LIVE_RELOAD;
+    if (typeof raw !== 'string')
+        return false;
+    const v = raw.trim().toLowerCase();
+    return v === '0' || v === 'false' || v === 'off' || v === 'no';
+})();
+const hmrAngularLiveReload = hmrActive && !angularLiveReloadDisabledByEnv;
 const projectRoot = process.cwd();
 const tsConfigAppPath = path.resolve(projectRoot, 'tsconfig.app.json');
 const tsConfigPath = path.resolve(projectRoot, 'tsconfig.json');
@@ -266,48 +217,31 @@ function createAngularPlugins(opts) {
         return true;
     };
     return [
-        // HMR self-registration runs in two phases:
-        //
-        //   1. (this plugin, `enforce: 'pre'`) Walk the raw TypeScript
-        //      source for each user `.ts` file and record the names of
-        //      any `@Component`-decorated classes into the shared
-        //      `componentsByCleanId` map. Discovery has to happen on the
-        //      raw source because the Analog Angular plugin rewrites
-        //      `@Component(...)` into static metadata calls and removes
-        //      the textual decorator pattern.
+        // HMR self-registration runs in two steps:
         //
-        //   2. (`ns-component-hmr-register-post`, `enforce: 'post'`)
-        //      After the Analog Angular plugin has compiled the file,
-        //      append the global `__NS_HMR_REGISTER_COMPONENT__`
-        //      registration calls keyed by the names recorded in step 1.
+        //   1. (this plugin, `enforce: 'pre'`) Record the names of
+        //      `@Component`-decorated classes from the RAW TypeScript source
+        //      into `componentsByCleanId` — discovery must happen pre-compile
+        //      because the Analog plugin rewrites the textual decorator away.
+        //   2. (`ns-component-hmr-register-post`, `enforce: 'post'`) Append the
+        //      `__NS_HMR_REGISTER_COMPONENT__` calls to the COMPILED output.
         //
-        // Why the two-phase split: the Analog Angular plugin's `transform`
-        // returns its OWN regenerated compiled output (from its internal
-        // `outputFiles` cache populated at `buildStart`), discarding any
-        // code modifications applied earlier in the pipeline. We
-        // previously appended the registration snippet here, in the pre
-        // plugin, and the snippet was silently dropped — leaving the
-        // HMR class registry empty and `getFreshComponentClass` returning
-        // `found=false reason=no-registry` after every reboot.
+        // The split is mandatory: Analog's `transform` returns its own compiled
+        // output (from its `outputFiles` cache), silently discarding any code
+        // modification made earlier in the pipeline — appending in the pre
+        // plugin leaves the HMR class registry empty.
         //
-        // Placement notes that still apply:
-        //   - `apply: 'serve'`: the registry runtime hook is dev-only;
-        //     production builds never need self-registration.
-        //   - Intentionally NOT gated on `hmrActive`. The injected
-        //     snippet self-guards with
-        //     `typeof globalThis.__NS_HMR_REGISTER_COMPONENT__ === 'function'`,
-        //     so it's a no-op when the runtime hook isn't installed
-        //     (e.g. `--no-hmr` users still serving modules through
-        //     Vite). Gating the transform itself on `hmrActive` produced
-        //     a silent failure mode where `--no-hmr` users got HMR
-        //     machinery up but never got the registration calls
-        //     injected, leaving the registry empty.
+        // `apply: 'serve'` (registry hook is dev-only) but intentionally NOT
+        // gated on `hmrActive`: the injected snippet self-guards on
+        // `typeof globalThis.__NS_HMR_REGISTER_COMPONENT__ === 'function'`, and
+        // gating the transform itself left `--no-hmr` users with an empty
+        // registry.
         {
             name: 'ns-component-hmr-register',
             enforce: 'pre',
             apply: 'serve',
             transform(code, id) {
-                const cleanId = id.split('?', 1)[0];
+                const cleanId = normalizeAngularWatchPath(id);
                 if (!isCandidateComponentTs(cleanId))
                     return null;
                 const componentNames = findComponentClassNames(code);
@@ -320,7 +254,7 @@ function createAngularPlugins(opts) {
                 }
                 componentsByCleanId.set(cleanId, componentNames);
                 if (verbose) {
-                    console.info(`[ns-hmr-diag][ns-component-hmr-register] discovered ${componentNames.length} component(s) in ${cleanId} (${componentNames.join(', ')})`);
+                    console.info(`[ns-hmr][ns-component-hmr-register] discovered ${componentNames.length} component(s) in ${cleanId} (${componentNames.join(', ')})`);
                 }
                 // Discovery only — never modify the raw TS source. Any
                 // modification here is discarded by the Analog Angular
@@ -329,43 +263,31 @@ function createAngularPlugins(opts) {
                 return null;
             },
         },
-        // Phase 2: append the HMR registration snippet to the compiled
-        // JS output produced by `@analogjs/vite-plugin-angular`. Runs
-        // `enforce: 'post'` so we see the post-Angular code (where the
-        // pre plugin's work would otherwise be discarded). Reads the
-        // component names recorded by the pre plugin via
-        // `componentsByCleanId`.
+        // Step 2: append the HMR registration snippet to the compiled output
+        // (post-Analog), keyed by the names recorded in step 1.
         {
             name: 'ns-component-hmr-register-post',
             enforce: 'post',
             apply: 'serve',
             transform(code, id) {
-                const cleanId = id.split('?', 1)[0];
+                const cleanId = normalizeAngularWatchPath(id);
                 if (!isCandidateComponentTs(cleanId))
                     return null;
                 const componentNames = componentsByCleanId.get(cleanId);
                 if (!componentNames || componentNames.length === 0)
                     return null;
-                // Idempotency: the Vite cache may replay the transform
-                // pipeline on cached modules. The marker comment is
-                // inserted by `appendComponentHmrRegistration` and
-                // guards against double-injection. We also defensively
-                // short-circuit here so we don't have to allocate the
-                // suffix string on every cached re-run.
+                // Idempotency: Vite may replay transforms on cached modules; the
+                // marker guards against double-injection.
                 if (code.includes(HMR_REGISTER_MARKER))
                     return null;
                 const result = appendComponentHmrRegistration(code, componentNames);
                 if (!result.code)
                     return null;
                 if (verbose) {
-                    console.info(`[ns-hmr-diag][ns-component-hmr-register-post] appended registrations for ${result.componentNames.length} component(s) in ${cleanId} (${result.componentNames.join(', ')})`);
+                    console.info(`[ns-hmr][ns-component-hmr-register-post] appended registrations for ${result.componentNames.length} component(s) in ${cleanId} (${result.componentNames.join(', ')})`);
                 }
-                // Returning `null` for the source map is acceptable for
-                // dev: lines 1..N (the original compiled body) keep
-                // the upstream Angular source map; the appended snippet
-                // is invisible to debuggers but harmless. For
-                // production-grade source maps a MagicString-based
-                // pass-through could be used; not required for HMR.
+                // map: null is fine for dev — the appended snippet sits after the
+                // original body, so upstream line mappings stay valid.
                 return { code: result.code, map: null };
             },
         },
@@ -383,14 +305,10 @@ function createAngularPlugins(opts) {
                 for (const assetPath of assetPaths) {
                     this.addWatchFile(assetPath);
                 }
-                // Diagnostic: surface which .ts files we've registered
-                // asset (template/styleUrls) dependencies for. This is
-                // the first fence the HTML→TS invalidation pipeline must
-                // pass — if we never see a [tracking] log for the
-                // component we're editing, the watcher will never fire
-                // and `pendingComponentInvalidations` stays empty.
+                // First fence of the HTML→TS invalidation pipeline: no [tracking]
+                // log for a component means the watcher can never fire for it.
                 if (verbose) {
-                    console.info(`[ns-hmr-diag][angular-template-deps] [tracking] componentKey=${componentKey} assets=${assetPaths.length} (${assetPaths.slice(0, 4).join(', ')})`);
+                    console.info(`[ns-hmr][angular-template-deps] [tracking] componentKey=${componentKey} assets=${assetPaths.length} (${assetPaths.slice(0, 4).join(', ')})`);
                 }
                 return null;
             },
@@ -407,7 +325,7 @@ function createAngularPlugins(opts) {
                         pendingComponentInvalidations.add(componentPath);
                     }
                     if (verbose) {
-                        console.info(`[ns-hmr-diag][angular-template-deps] watchChange [via assetToComponents] changed=${changedPath} → invalidating ${components.size} component(s):`, Array.from(components));
+                        console.info(`[ns-hmr][angular-template-deps] watchChange [via assetToComponents] changed=${changedPath} → invalidating ${components.size} component(s):`, Array.from(components));
                     }
                     return;
                 }
@@ -418,11 +336,15 @@ function createAngularPlugins(opts) {
                         const componentKey = normalizeAngularWatchKey(componentPath);
                         pendingComponentInvalidations.add(componentKey);
                         if (verbose) {
-                            console.info(`[ns-hmr-diag][angular-template-deps] watchChange [via fallback .html→.ts] changed=${changedPath} componentKey=${componentKey}`);
+                            console.info(`[ns-hmr][angular-template-deps] watchChange [via fallback .html→.ts] changed=${changedPath} componentKey=${componentKey}`);
                         }
                     }
-                    else if (verbose) {
-                        console.info(`[ns-hmr-diag][angular-template-deps] watchChange [no companion .ts found] changed=${changedPath} expectedTs=${componentPath}`);
+                    else {
+                        // Truly anomalous: a watched template/style asset has no companion
+                        // `.ts` file, so we cannot route the edit through the Angular
+                        // HMR pipeline. Always-on warning so it surfaces in non-verbose
+                        // runs — silent fallback would hide a real wiring break.
+                        console.warn(`[ns-hmr][angular-template-deps] watchChange [no companion .ts found] changed=${changedPath} expectedTs=${componentPath}`);
                     }
                 }
             },
@@ -432,7 +354,7 @@ function createAngularPlugins(opts) {
                     return null;
                 pendingComponentInvalidations.delete(componentPath);
                 if (verbose) {
-                    console.info(`[ns-hmr-diag][angular-template-deps] shouldTransformCachedModule → re-transform componentKey=${componentPath}`);
+                    console.info(`[ns-hmr][angular-template-deps] shouldTransformCachedModule → re-transform componentKey=${componentPath}`);
                 }
                 return true;
             },
@@ -440,17 +362,94 @@ function createAngularPlugins(opts) {
         // Transform Angular partial declarations in node_modules to avoid runtime JIT
         // Pass the project root so linker deps resolve from the app, not the plugin package.
         angularLinkerVitePlugin(process.cwd()),
-        // Simplify: rely on Vite pre plugin (load/transform) for linking; Rollup safety net disabled unless re-enabled later
-        // angularRollupLinker(process.cwd()),
+        // A Rollup-phase linker safety net (angularRollupLinker) is additionally
+        // appended for HMR sessions — see `enableRollupLinker` below.
         ...angular({
             experimental: {
                 useAngularCompilationAPI: opts.useAngularCompilationAPI,
             },
-            liveReload: false, // Disable live reload in favor of HMR
+            // `liveReload` enables Angular's web-style in-place template HMR:
+            //   1. `_enableHmr = true` on the TS compiler — each compiled component
+            //      `.mjs` emits `<ClassName>_HmrLoad` plus an
+            //      `import.meta.hot.on('angular:component-update', ...)` listener.
+            //   2. A `/@ng/component?c=<id>` middleware serving recompiled
+            //      `_UpdateMetadata` sources on demand.
+            //   3. `angular:component-update` broadcasts on `.html`/style edits so
+            //      the runtime calls `ɵɵreplaceMetadata` on the live class — views
+            //      recreate in-place with NO reboot and NO route navigation (the
+            //      reboot path via `__reboot_ng_modules__` remains for `.ts` edits).
+            //
+            // Load-bearing interactions:
+            //   - Analog's middleware matches `req.url.includes('/@ng/component')`
+            //     (substring), so the `/ns/m/`-prefixed device fetch still hits it.
+            //   - The device client (`hmr/client/protocol-dispatch.ts`) forwards
+            //     `{ type: 'custom', event, data }` to `import.meta.hot.on`
+            //     listeners and short-circuits before the reboot path for
+            //     `angular:component-update`.
+            //   - `hmr/server/websocket.ts` skips its own `ns:angular-update`
+            //     broadcast for `.html`/component-style edits to avoid double-fire.
+            //   - Rollback to reboot-only: set `NS_VITE_ANGULAR_LIVE_RELOAD=0`.
+            liveReload: hmrAngularLiveReload,
+            // NativeScript can't consume `externalRuntimeStyles` (runtime-loaded
+            // `<hash>.css` URLs need a browser CSSOM/`<link>` pipeline), so keep
+            // component styles inlined in the metadata's `styles: [...]` array.
+            // Independent of `liveReload` — template HMR stays on. The option is
+            // honored by our patched Analog plugin (upstream PR pending) and is a
+            // no-op on stock releases; not yet in the published `PluginOptions`.
+            // @ts-expect-error -- pending upstream Analog type publish
+            externalRuntimeStyles: false,
             tsconfig: tsConfig,
+            // Forward Angular-style file replacements (e.g. `environment.ts`
+            // → `environment.stg.ts`) directly into the Analog plugin so the
+            // Angular TypeScript host (which reads source files via its own
+            // CompilerHost, bypassing Vite's load chain) sees the swap. This
+            // is the same hook Angular CLI uses for `fileReplacements` in
+            // `angular.json` build configurations.
+            fileReplacements: opts.fileReplacements ?? [],
+            // Component-HMR id alignment. Angular's compiler embeds each
+            // component's HMR id relative to the TS compilation's base path —
+            // in an Nx monorepo that's the WORKSPACE root (tsconfig.base.json's
+            // baseUrl), not the app dir. Analog uses `workspaceRoot` both to
+            // build the `angular:component-update` broadcast id
+            // (`relative(workspaceRoot, file)`) and to resolve `/@ng/component?c=`
+            // fetches back to absolute paths (`resolve(workspaceRoot, id)`).
+            // Defaulting to `process.cwd()` (the app dir) makes the broadcast id
+            // `src/...` while every compiled listener guards on
+            // `apps/<app>/src/...` — `d.id === id` never matches, so template
+            // edits dispatch cleanly but visually apply nothing. Default to the
+            // monorepo root when one exists so all three id producers agree;
+            // standalone apps (no monorepo root) keep the cwd behavior.
+            workspaceRoot: opts.workspaceRoot ?? getMonorepoWorkspaceRoot(process.cwd()) ?? process.cwd(),
         }),
         // Post-phase linker to catch any declarations introduced after other transforms (including project code)
         angularLinkerVitePluginPost(process.cwd()),
+        // Re-inject `/* @vite-ignore */` onto Angular's HMR initializer dynamic
+        // imports. Angular emits `import(/* @vite-ignore */ i0.ɵɵgetReplaceMetadataURL(...))`,
+        // but the annotation gets stripped in the post-Angular pipeline
+        // (empirically the linker's `compact: false` Babel pass) — Vite's static
+        // analyzer then rewrites the call through its runtime resolver, which
+        // throws `TypeError at ɵɵgetReplaceMetadataURL` on the iOS device.
+        // `enforce: 'post'` sees the file after every comment-stripping
+        // transform; `apply: 'serve'` because the initializer is `ngDevMode`-
+        // gated and never runs in production. Idempotent.
+        {
+            name: 'ns-angular-hmr-vite-ignore',
+            enforce: 'post',
+            apply: 'serve',
+            transform(code, id) {
+                if (!hmrAngularLiveReload)
+                    return null;
+                const cleanId = normalizeAngularWatchPath(id);
+                if (!cleanId.endsWith('.ts') && !cleanId.endsWith('.mjs') && !cleanId.endsWith('.js'))
+                    return null;
+                if (cleanId.includes('/node_modules/'))
+                    return null;
+                const next = injectAngularHmrViteIgnore(code);
+                if (next === code)
+                    return null;
+                return { code: next, map: null };
+            },
+        },
         // Enforce: fully disable dependency optimization during serve to avoid rxjs esm5 crawling and OOM
         {
             name: 'ns-disable-optimize-deps',
@@ -460,7 +459,7 @@ function createAngularPlugins(opts) {
                 const od = userConfig?.optimizeDeps || {};
                 const prevExclude = Array.isArray(od.exclude) ? od.exclude : [];
                 const exclude = new Set(prevExclude);
-                ['@nativescript/core', 'rxjs', '@valor/nativescript-websockets', 'set-value', 'react', 'react-reconciler', 'react-nativescript'].forEach((x) => exclude.add(x));
+                [...NS_OPTIMIZE_DEPS_EXCLUDE, 'rxjs'].forEach((x) => exclude.add(x));
                 return {
                     optimizeDeps: {
                         noDiscovery: true,
@@ -481,7 +480,7 @@ function createAngularPlugins(opts) {
                 deps.entries = [];
                 deps.include = [];
                 const exclude = new Set(Array.isArray(deps.exclude) ? deps.exclude : []);
-                ['@nativescript/core', 'rxjs', '@valor/nativescript-websockets', 'set-value', 'react', 'react-reconciler', 'react-nativescript'].forEach((x) => exclude.add(x));
+                [...NS_OPTIMIZE_DEPS_EXCLUDE, 'rxjs'].forEach((x) => exclude.add(x));
                 deps.exclude = Array.from(exclude);
                 const rolldownOptions = (deps.rolldownOptions || (deps.rolldownOptions = {}));
                 rolldownOptions.plugins = [];
@@ -489,7 +488,7 @@ function createAngularPlugins(opts) {
         },
     ];
 }
-export const angularConfig = ({ mode }) => {
+export const angularConfig = ({ mode, fileReplacements, workspaceRoot, }) => {
     const useSingleBundleDevOutput = mode === 'development' && !hmrActive;
     const plugins = createAngularPlugins({
         // Vite build --watch with the legacy Analog compilation path can regress
@@ -497,10 +496,11 @@ export const angularConfig = ({ mode }) => {
         // Restrict the newer compilation API to NativeScript's development no-HMR
         // flow, which is where the unstable rebuilds occur today.
         useAngularCompilationAPI: useSingleBundleDevOutput,
+        fileReplacements,
+        workspaceRoot,
     });
+    // Angular browser animations are never used in NativeScript; the stub alias below is unconditional.
     const disableAnimations = true;
-    //process.env.NS_DISABLE_NG_ANIMATIONS === "1" ||
-    //process.env.NS_DISABLE_NG_ANIMATIONS === "true";
     // Post-link emitted chunks to catch any remaining partial declarations that slipped through
     // due to plugin order or external transforms.
     const applyAngularChunkPostProcessing = (code, options = {}) => {
@@ -517,17 +517,16 @@ export const angularConfig = ({ mode }) => {
         apply: 'build',
         enforce: 'post',
         async generateBundle(_options, bundle) {
+            function isNsAngularPolyfillsModule(id) {
+                return normalizeAngularWatchPath(id).includes('node_modules/@nativescript/angular/fesm2022/nativescript-angular-polyfills.mjs');
+            }
             function isNsAngularPolyfillsChunk(chunk) {
                 if (!chunk || !chunk.modules)
                     return false;
-                return Object.keys(chunk.modules).some((m) => m.includes('node_modules/@nativescript/angular/fesm2022/nativescript-angular-polyfills.mjs'));
+                return Object.keys(chunk.modules).some(isNsAngularPolyfillsModule);
             }
-            const { babel } = await ensureSharedAngularLinker(process.cwd());
-            if (!babel)
-                return;
-            const fileSystem = await resolveAngularFileSystem(process.cwd());
-            const linkerFactory = await importLinkerFactory();
-            if (!linkerFactory)
+            const { babel, createLinker } = await getAngularLinkerFactory(process.cwd());
+            if (!babel || !createLinker)
                 return;
             const strict = process.env.NS_STRICT_NG_LINK === '1' || process.env.NS_STRICT_NG_LINK === 'true';
             const enforceStrict = process.env.NS_STRICT_NG_LINK_ENFORCE === '1' || process.env.NS_STRICT_NG_LINK_ENFORCE === 'true';
@@ -547,21 +546,12 @@ export const angularConfig = ({ mode }) => {
                         continue;
                     const isNsPolyfills = isNsAngularPolyfillsChunk(chunk);
                     try {
-                        // Create a FRESH linker plugin per chunk — the linker may have
-                        // internal state that becomes stale across watch-mode rebuild cycles.
-                        const freshPlugin = linkerFactory({ sourceMapping: false, fileSystem });
-                        const res = await babel.transformAsync(code, {
-                            filename: fileName,
-                            configFile: false,
-                            babelrc: false,
-                            sourceMaps: false,
-                            compact: false,
-                            plugins: [freshPlugin],
-                        });
-                        const linkedCode = res?.code && res.code !== code ? res.code : code;
-                        const finalCode = applyAngularChunkPostProcessing(linkedCode, { vendorInjectExport });
+                        // Fresh plugin per chunk — avoids stale linker state across watch-mode rebuilds.
+                        const linked = await runAngularLinker(code, { filename: fileName, projectRoot: process.cwd(), freshPlugin: true });
+                        const finalCode = applyAngularChunkPostProcessing(linked ?? code, { vendorInjectExport });
                         if (finalCode !== code) {
                             chunk.code = finalCode;
+                            recordLinkerHit('post');
                             if (debug) {
                                 console.log('[ns-angular-linker][post] linked', fileName, isNsPolyfills ? '(polyfills)' : '');
                             }
@@ -577,16 +567,20 @@ export const angularConfig = ({ mode }) => {
                     }
                 }
             }
+            // Evidence for pruning the stacked linker layers: print which of the
+            // five layers actually linked anything this build. A layer that
+            // reports 0 across the full flavor matrix is a candidate for removal.
+            reportLinkerLayerStats();
             if (strict && unlinked.length) {
                 const details = [];
                 for (const fname of unlinked) {
                     const chunk = bundle[fname];
                     const modIds = chunk?.modules
                         ? Object.keys(chunk.modules)
-                            .filter((m) => /node_modules\/(?:@angular|@nativescript\/angular)\//.test(m))
+                            .filter((m) => /node_modules\/(?:@angular|@nativescript\/angular)\//.test(normalizeAngularWatchPath(m)))
                             .slice(0, 8)
                         : [];
-                    const isOnlyPolyfills = modIds.length > 0 && modIds.every((m) => m.includes('node_modules/@nativescript/angular/fesm2022/nativescript-angular-polyfills.mjs'));
+                    const isOnlyPolyfills = modIds.length > 0 && modIds.every(isNsAngularPolyfillsModule);
                     if (isOnlyPolyfills)
                         continue;
                     let snippet = '';
@@ -629,32 +623,18 @@ export const angularConfig = ({ mode }) => {
             try {
                 let transformed = code;
                 if (containsRealNgDeclare(code)) {
-                    const { babel } = await ensureSharedAngularLinker(process.cwd());
-                    if (!babel)
-                        return null;
-                    const fileSystem = await resolveAngularFileSystem(process.cwd());
-                    // Fresh plugin per chunk — avoids stale linker state across watch-mode rebuilds
-                    const freshPlugin = (await importLinkerFactory())?.({ sourceMapping: false, fileSystem });
-                    if (!freshPlugin)
+                    const { babel, createLinker } = await getAngularLinkerFactory(process.cwd());
+                    if (!babel || !createLinker)
                         return null;
-                    const runLink = async (input) => {
-                        const result = await babel.transformAsync(input, {
-                            filename,
-                            configFile: false,
-                            babelrc: false,
-                            sourceMaps: false,
-                            compact: false,
-                            plugins: [freshPlugin],
-                        });
-                        return result?.code ?? input;
-                    };
-                    transformed = await runLink(code);
+                    // Fresh plugin per pass — avoids stale linker state across watch-mode rebuilds.
+                    transformed = (await runAngularLinker(code, { filename, projectRoot: process.cwd(), freshPlugin: true })) ?? code;
                     if (containsRealNgDeclare(transformed)) {
-                        transformed = await runLink(transformed);
+                        transformed = (await runAngularLinker(transformed, { filename, projectRoot: process.cwd(), freshPlugin: true })) ?? transformed;
                     }
                 }
                 transformed = applyAngularChunkPostProcessing(transformed);
                 if (transformed !== code) {
+                    recordLinkerHit('render');
                     if (debug) {
                         console.log('[ns-angular-linker][render] linked', filename);
                     }
@@ -668,9 +648,8 @@ export const angularConfig = ({ mode }) => {
         },
     };
     const enableRollupLinker = process.env.NS_ENABLE_ROLLUP_LINKER === '1' || process.env.NS_ENABLE_ROLLUP_LINKER === 'true' || hmrActive;
-    // Build a single merged alias array to avoid property override conflicts.
-    // Previously the disableAnimations spread added a second `resolve` key
-    // that silently clobbered the fesm2022 and RxJS aliases.
+    // Single merged alias array — a second `resolve` key from a conditional
+    // spread would silently clobber the fesm2022 and RxJS aliases.
     const angularAliases = [
         // Map Angular deep ESM paths to bare package ids
         { find: /^@angular\/([^/]+)\/fesm2022\/.*\.mjs$/, replacement: '@angular/$1' },