@obsidiane/meridiane 2.0.5 → 2.0.6

package/templates/_lib_template/src/lib/bridge.types.ts

@@ -31,3 +31,40 @@ export interface BridgeDefaults {
  */
 export type MercureTopicMode = 'url' | 'iri';
 
+/**
+ * Controls how SSE connections are managed.
+ * - `single`: each watch subscription opens its own SSE connection
+ * - `auto`: subscriptions are shared and split into multiple connections only when URL length is too large
+ */
+export type MercureConnectionMode = 'single' | 'auto';
+
+/**
+ * Per-subscription realtime override.
+ * - `true`: force an isolated SSE connection for this watch call
+ * - `false`/`undefined`: use adapter strategy (`single` or `auto`)
+ */
+export interface WatchConnectionOptions {
+  newConnection?: boolean;
+}
+
+export type RealtimeConnectionScope = 'shared' | 'dedicated';
+
+export type RealtimeConnectionStatus = 'connecting' | 'connected' | 'closed';
+
+export interface RealtimeConnectionDiagnostics {
+  id: string;
+  scope: RealtimeConnectionScope;
+  status: RealtimeConnectionStatus;
+  topicCount: number;
+  topics: string[];
+  urlLength: number;
+}
+
+export interface RealtimeDiagnostics {
+  mode: MercureConnectionMode;
+  maxUrlLength: number;
+  totalConnections: number;
+  sharedConnections: number;
+  dedicatedConnections: number;
+  connections: RealtimeConnectionDiagnostics[];
+}

package/templates/_lib_template/src/lib/facades/bridge.facade.ts

@@ -9,6 +9,22 @@ import {API_BASE_URL, BRIDGE_WITH_CREDENTIALS} from '../tokens';
 import {AnyQuery, Collection, HttpCallOptions, HttpRequestConfig, Iri, IriRequired, Item} from '../ports/resource-repository.port';
 import {SubscribeFilter} from '../ports/realtime.port';
 import {resolveUrl} from '../utils/url';
+import {RealtimeDiagnostics, WatchConnectionOptions} from '../bridge.types';
+
+export type TypedEvent<TType extends string = string, TPayload = unknown> = {
+  resourceType: TType;
+  payload: TPayload;
+};
+
+export type WatchTypesResult<R extends Record<string, any>> =
+  { [K in keyof R]: TypedEvent<K & string, R[K]> }[keyof R];
+
+export type WatchTypesConfig = {
+  /** Field name used as discriminator. Default: `@type` (JSON-LD). */
+  discriminator?: string;
+};
+
+export type WatchSubscriptionOptions = WatchConnectionOptions;
 
 /**
  * High-level facade for ad-hoc HTTP calls and Mercure subscriptions.
@@ -85,10 +101,14 @@ export class BridgeFacade {
 
   // ──────────────── SSE / Mercure ────────────────
 
-  watch$<T = Item>(iri: Iri | Iri[], subscribeFilter?: SubscribeFilter): Observable<T> {
+  watch$<T = Item>(
+    iri: Iri | Iri[],
+    subscribeFilter?: SubscribeFilter,
+    options?: WatchSubscriptionOptions
+  ): Observable<T> {
     const iris = (Array.isArray(iri) ? iri : [iri]).filter((v): v is string => typeof v === 'string' && v.length > 0);
     return this.realtime
-      .subscribe$<T>(iris, subscribeFilter)
+      .subscribe$<T>(iris, subscribeFilter, options)
       .pipe(
         map((event) => event.data),
         filter((data): data is T => data !== undefined),
@@ -96,13 +116,68 @@ export class BridgeFacade {
       );
   }
 
+  /**
+   * Watches a "multi-entity" topic and emits only payloads whose discriminator matches `resourceTypes`.
+   *
+   * Important:
+   * - filtering is done on payload content (e.g. `@type`), not on network topic provenance.
+   * - in shared mode (`connectionMode: 'auto'` without `newConnection`), events from another shared topic
+   *   can be emitted if they carry an allowed discriminator.
+   *
+   * For strict single-topic isolation, use a dedicated connection:
+   * `watchTypes$(..., ..., ..., { newConnection: true })`
+   * (or `connectionMode: 'single'` globally).
+   */
+  watchTypes$<R extends Record<string, any>>(
+    iri: Iri | Iri[],
+    resourceTypes: (keyof R & string)[],
+    cfg?: WatchTypesConfig,
+    options?: WatchSubscriptionOptions
+  ): Observable<WatchTypesResult<R>> {
+    const iris = (Array.isArray(iri) ? iri : [iri]).filter((v): v is string => typeof v === 'string' && v.length > 0);
+    const discriminator = cfg?.discriminator ?? '@type';
+    const allowedTypes = new Set(resourceTypes.filter((v): v is string => typeof v === 'string' && v.length > 0));
+
+    return this.realtime
+      .subscribeAll$<unknown>(iris, options)
+      .pipe(
+        map((event): WatchTypesResult<R> | undefined => {
+          const raw = event.data;
+
+          const resolvedType = readDiscriminator(raw, discriminator);
+          if (typeof resolvedType !== 'string') return undefined;
+          if (!allowedTypes.has(resolvedType)) return undefined;
+
+          const key = resolvedType as keyof R & string;
+          return {resourceType: key, payload: raw as R[keyof R]} as WatchTypesResult<R>;
+        }),
+        filter((evt): evt is WatchTypesResult<R> => !!evt),
+        share()
+      );
+  }
+
   unwatch(iri: Iri | Iri[]): void {
     const iris = (Array.isArray(iri) ? iri : [iri]).filter((v): v is string => typeof v === 'string' && v.length > 0);
     this.realtime.unsubscribe(iris);
   }
 
+  realtimeDiagnostics$(): Observable<RealtimeDiagnostics> {
+    return this.realtime.diagnostics$();
+  }
+
   private resolveUrl(path?: Iri): string {
     if (!path) throw new Error('BridgeFacade: missing url');
     return resolveUrl(this.apiBase, path);
   }
 }
+
+function readDiscriminator(raw: unknown, discriminator: string): string | undefined {
+  if (!raw || typeof raw !== 'object') return undefined;
+  const value = (raw as any)?.[discriminator];
+  if (typeof value === 'string') return value;
+  if (Array.isArray(value)) {
+    const first = value.find((v) => typeof v === 'string');
+    return typeof first === 'string' ? first : undefined;
+  }
+  return undefined;
+}

package/templates/_lib_template/src/lib/facades/facade.interface.ts

@@ -8,6 +8,7 @@ import {
   AnyQuery,
 } from '../ports/resource-repository.port';
 import {Observable} from 'rxjs';
+import {WatchConnectionOptions} from '../bridge.types';
 
 export interface Facade<T extends Item> {
   getCollection$(query?: AnyQuery, opts?: HttpCallOptions): Observable<Collection<T>>;
@@ -24,7 +25,7 @@ export interface Facade<T extends Item> {
 
   request$<R = unknown, B = unknown>(req: HttpRequestConfig<B>): Observable<R>;
 
-  watch$(iri: Iri | Iri[]): Observable<T>;
+  watch$(iri: Iri | Iri[], options?: WatchConnectionOptions): Observable<T>;
 
   unwatch(iri: Iri | Iri[]): void;
 }

package/templates/_lib_template/src/lib/facades/resource.facade.ts

@@ -13,6 +13,7 @@ import {RealtimePort, RealtimeStatus} from '../ports/realtime.port';
 import {toSignal} from '@angular/core/rxjs-interop';
 import {filter, map, Observable, share} from 'rxjs';
 import {Facade} from './facade.interface';
+import {WatchConnectionOptions} from '../bridge.types';
 
 export class ResourceFacade<T extends Item> implements Facade<T> {
 
@@ -60,9 +61,9 @@ export class ResourceFacade<T extends Item> implements Facade<T> {
    * Subscribes to real-time updates for one or many IRIs.
    * Undefined/empty values are ignored.
    */
-  watch$(iri: Iri | Iri[]): Observable<T> {
+  watch$(iri: Iri | Iri[], options?: WatchConnectionOptions): Observable<T> {
     const iris = (Array.isArray(iri) ? iri : [iri]).filter((v): v is string => typeof v === 'string' && v.length > 0);
-    return this.subscribeAndSync(iris);
+    return this.subscribeAndSync(iris, options);
   }
 
 
@@ -77,11 +78,12 @@ export class ResourceFacade<T extends Item> implements Facade<T> {
    */
   watchSubResource$<R>(
     iri: Iri | Iri[],
-    field: string
+    field: string,
+    options?: WatchConnectionOptions
   ): Observable<R> {
     const iris = (Array.isArray(iri) ? iri : [iri]).filter((v): v is string => typeof v === 'string' && v.length > 0);
     return this.realtime
-      .subscribe$<R>(iris, {field: field})
+      .subscribe$<R>(iris, {field: field}, options)
       .pipe(
         map(e => e.data),
         filter((d): d is R => d !== undefined),
@@ -89,9 +91,9 @@ export class ResourceFacade<T extends Item> implements Facade<T> {
       );
   }
 
-  protected subscribeAndSync(iris: string[]): Observable<T> {
+  protected subscribeAndSync(iris: string[], options?: WatchConnectionOptions): Observable<T> {
     return this.realtime
-      .subscribe$<T>(iris)
+      .subscribe$<T>(iris, undefined, options)
       .pipe(
         map(event => event.data),
         filter((data): data is T => data !== undefined),

package/templates/_lib_template/src/lib/ports/realtime.port.ts

@@ -1,5 +1,6 @@
 import {Observable} from 'rxjs';
 import {Iri} from './resource-repository.port';
+import {WatchConnectionOptions} from '../bridge.types';
 
 export type RealtimeStatus = 'connecting' | 'connected' | 'closed';
 
@@ -15,11 +16,34 @@ export interface SseOptions {
 
 export interface RealtimeEvent<T> {
   iri: string;
+  /**
+   * Matched subscription topic (normalized).
+   *
+   * - When matching by `@id`, this is typically the same as `iri`.
+   * - When matching by a relation field (e.g. `conversation`), this is the parent topic IRI.
+   */
+  topic?: string;
   data?: T;
 }
 
 export type SubscribeFilter = {
-  field: string;
+  /**
+   * Single relation path used to match events to subscription topics.
+   * Example: `conversation` or `embedded.author`.
+   */
+  field?: string;
+  /**
+   * Multiple relation paths used to match events to subscription topics.
+   */
+  fields?: string[];
+  /**
+   * When relation fields are provided, also include events whose `@id` matches the subscribed topics.
+   *
+   * Default:
+   * - `true` when no relation fields are provided (match by `@id`)
+   * - `false` when relation fields are provided (sub-resource mode)
+   */
+  includeSelf?: boolean;
 };
 
 export interface RealtimePort {
@@ -28,7 +52,14 @@ export interface RealtimePort {
    *
    * Note: topics must be stable strings. Undefined values are ignored by the adapter.
    */
-  subscribe$<T>(iris: Iri[], filter?: SubscribeFilter): Observable<RealtimeEvent<T>>;
+  subscribe$<T>(iris: Iri[], filter?: SubscribeFilter, options?: WatchConnectionOptions): Observable<RealtimeEvent<T>>;
+
+  /**
+   * Subscribes to all JSON payloads received on the given Mercure topics.
+   *
+   * No payload-to-topic matching is applied.
+   */
+  subscribeAll$<T>(iris: Iri[], options?: WatchConnectionOptions): Observable<RealtimeEvent<T>>;
 
   unsubscribe(iris: Iri[]): void;
 

package/templates/_lib_template/src/lib/provide-bridge.ts

@@ -5,10 +5,12 @@ import {
   BRIDGE_DEFAULTS,
   BRIDGE_LOGGER,
   BRIDGE_WITH_CREDENTIALS,
+  MERCURE_CONNECTION_MODE,
   MERCURE_HUB_URL,
+  MERCURE_MAX_URL_LENGTH,
   MERCURE_TOPIC_MODE,
 } from './tokens';
-import {BridgeDefaults, BridgeLogger, MercureTopicMode} from './bridge.types';
+import {BridgeDefaults, BridgeLogger, MercureConnectionMode, MercureTopicMode} from './bridge.types';
 import {contentTypeInterceptor} from './interceptors/content-type.interceptor';
 import {bridgeDefaultsInterceptor} from './interceptors/bridge-defaults.interceptor';
 import {bridgeDebugInterceptor} from './interceptors/bridge-debug.interceptor';
@@ -25,6 +27,17 @@ export interface BridgeMercureOptions {
   hubUrl?: string;
   init?: RequestInit;
   topicMode?: MercureTopicMode;
+  /**
+   * Connection strategy for SSE subscriptions.
+   * - `single`: one SSE connection per watch subscription
+   * - `auto` (default): shared connections with automatic URL-length sharding
+   */
+  connectionMode?: MercureConnectionMode;
+  /**
+   * Maximum Mercure URL length before auto-sharding topics into multiple connections.
+   * Used only when `connectionMode: 'auto'`. Default: `1900`.
+   */
+  maxUrlLength?: number;
 }
 
 export interface BridgeOptions {
@@ -70,6 +83,8 @@ export function provideBridge(opts: BridgeOptions): EnvironmentProviders {
   const resolvedMercureInit: RequestInit = mercure?.init ?? {credentials: 'include' as RequestCredentials};
   const resolvedMercureHubUrl = mercure?.hubUrl;
   const resolvedMercureTopicMode: MercureTopicMode = mercure?.topicMode ?? 'url';
+  const resolvedMercureConnectionMode: MercureConnectionMode = mercure?.connectionMode ?? 'auto';
+  const resolvedMercureMaxUrlLength = normalizeMercureMaxUrlLength(mercure?.maxUrlLength, 1900);
   const withCredentials = resolveWithCredentials(resolvedMercureInit);
 
   const loggerProvider: BridgeLogger = createBridgeLogger(debug);
@@ -92,6 +107,8 @@ export function provideBridge(opts: BridgeOptions): EnvironmentProviders {
     {provide: BRIDGE_WITH_CREDENTIALS, useValue: withCredentials},
     ...(resolvedMercureHubUrl ? [{provide: MERCURE_HUB_URL, useValue: resolvedMercureHubUrl}] : []),
     {provide: MERCURE_TOPIC_MODE, useValue: resolvedMercureTopicMode},
+    {provide: MERCURE_CONNECTION_MODE, useValue: resolvedMercureConnectionMode},
+    {provide: MERCURE_MAX_URL_LENGTH, useValue: resolvedMercureMaxUrlLength},
     {provide: BRIDGE_DEFAULTS, useValue: defaults ?? {}},
     {provide: BRIDGE_LOGGER, useValue: loggerProvider},
   ]);
@@ -113,6 +130,11 @@ function resolveWithCredentials(init: RequestInit | undefined): boolean {
   return anyInit.withCredentials === true || init.credentials === 'include';
 }
 
+function normalizeMercureMaxUrlLength(input: unknown, fallback: number): number {
+  const value = typeof input === 'number' ? Math.floor(input) : fallback;
+  return Number.isFinite(value) && value >= 256 ? value : fallback;
+}
+
 function createAuthInterceptors(auth?: BridgeAuth): HttpInterceptorFn[] {
   if (!auth) return [];
 

package/templates/_lib_template/src/lib/tokens.ts

@@ -1,5 +1,5 @@
 import {InjectionToken} from '@angular/core';
-import {BridgeDefaults, BridgeLogger, MercureTopicMode} from './bridge.types';
+import {BridgeDefaults, BridgeLogger, MercureConnectionMode, MercureTopicMode} from './bridge.types';
 
 /** Base URL of the API (e.g. `http://localhost:8000`). */
 export const API_BASE_URL = new InjectionToken<string>('API_BASE_URL');
@@ -15,6 +15,10 @@ export const BRIDGE_WITH_CREDENTIALS = new InjectionToken<boolean>('BRIDGE_WITH_
 
 export const MERCURE_TOPIC_MODE = new InjectionToken<MercureTopicMode>('MERCURE_TOPIC_MODE');
 
+export const MERCURE_CONNECTION_MODE = new InjectionToken<MercureConnectionMode>('MERCURE_CONNECTION_MODE');
+
+export const MERCURE_MAX_URL_LENGTH = new InjectionToken<number>('MERCURE_MAX_URL_LENGTH');
+
 export const BRIDGE_LOGGER = new InjectionToken<BridgeLogger>('BRIDGE_LOGGER');
 
 export const BRIDGE_DEFAULTS = new InjectionToken<BridgeDefaults>('BRIDGE_DEFAULTS');

package/tools/app/bridge-workflow.js

@@ -1,5 +1,6 @@
 import process from 'node:process';
 import path from 'node:path';
+import fs from 'node:fs/promises';
 
 import { readOpenApiSpec } from '../infra/spec-loader.js';
 import { generateBridgeWorkspace } from '../infra/generate/bridge.js';
@@ -69,6 +70,7 @@ export async function runBridgeWorkflow({
   const distDir = path.join(distRoot, libName);
   const packRel = packRelativeTo ? path.relative(packRelativeTo, distDir) : distDir;
   log?.step?.(`npm pack (${packRel})`);
+  await cleanupPackedTarballs(distDir);
   const packCode = await runCommand('npm', ['pack'], {
     cwd: distDir,
     env: {
@@ -83,3 +85,9 @@ export async function runBridgeWorkflow({
 
   return { workspaceRoot, distRoot, distDir, npmCacheDir };
 }
+
+async function cleanupPackedTarballs(distDir) {
+  const entries = await fs.readdir(distDir, {withFileTypes: true});
+  const tarballs = entries.filter((entry) => entry.isFile() && entry.name.endsWith('.tgz'));
+  await Promise.all(tarballs.map((entry) => fs.rm(path.join(distDir, entry.name), {force: true})));
+}

package/tools/infra/dev-support.js

@@ -108,5 +108,82 @@ export async function installPackageFromDist({ packageName, distDir, appRoot, lo
     filter: (src) => !src.endsWith('.tgz'),
   });
 
+  await invalidateAngularViteDependencyCache({ appRoot, packageName, log });
+
   return pkgDir;
 }
+
+async function invalidateAngularViteDependencyCache({ appRoot, packageName, log }) {
+  const viteDepsRoots = await findAngularViteDepsRoots(appRoot);
+  if (viteDepsRoots.length === 0) return;
+
+  const cacheBase = packageNameToViteCacheBase(packageName);
+  let removed = 0;
+
+  for (const depsRoot of viteDepsRoots) {
+    const files = [
+      `${cacheBase}.js`,
+      `${cacheBase}.js.map`,
+      `${cacheBase}.mjs`,
+      `${cacheBase}.mjs.map`,
+    ];
+
+    for (const fileName of files) {
+      const p = path.join(depsRoot, fileName);
+      try {
+        await fs.rm(p, { force: true });
+        removed += 1;
+      } catch {
+        // ignore
+      }
+    }
+
+    // Metadata keeps dependency hashes/entries; remove it to force a clean re-optimization.
+    try {
+      await fs.rm(path.join(depsRoot, '_metadata.json'), { force: true });
+      removed += 1;
+    } catch {
+      // ignore
+    }
+  }
+
+  if (removed > 0) {
+    log?.info?.(`cache Angular/Vite invalidé (${removed} fichier(s)) pour ${packageName}`);
+  }
+}
+
+function packageNameToViteCacheBase(packageName) {
+  const normalized = String(packageName || '').trim();
+  // Example: "@obsidiane/bridge-sandbox" -> "@obsidiane_bridge-sandbox"
+  return normalized.replace('/', '_');
+}
+
+async function findAngularViteDepsRoots(appRoot) {
+  const angularCacheRoot = path.join(appRoot, '.angular', 'cache');
+  const roots = [];
+
+  async function walk(dir, depth) {
+    if (depth > 8) return;
+
+    let entries;
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    const hasDeps = entries.some((e) => e.isDirectory() && e.name === 'deps');
+    if (hasDeps && path.basename(dir) === 'vite') {
+      roots.push(path.join(dir, 'deps'));
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name === 'node_modules') continue;
+      await walk(path.join(dir, entry.name), depth + 1);
+    }
+  }
+
+  await walk(angularCacheRoot, 0);
+  return roots;
+}

package/tools/infra/standalone-workspace.js

@@ -18,7 +18,7 @@ async function exists(p) {
   }
 }
 
-function toolchainPackageJson({ angularVersion }) {
+function toolchainPackageJson({ angularVersion, ngPackagrVersion, typescriptVersion, rxjsVersion, tslibVersion }) {
   const v = angularVersion;
   return {
     name: 'meridiane-standalone-workspace',
@@ -29,10 +29,10 @@ function toolchainPackageJson({ angularVersion }) {
       '@angular/compiler': v,
       '@angular/compiler-cli': v,
       '@angular/core': v,
-      'ng-packagr': '20.1.0',
-      rxjs: '7.8.2',
-      tslib: '2.8.1',
-      typescript: '5.8.3',
+      'ng-packagr': ngPackagrVersion,
+      rxjs: rxjsVersion,
+      tslib: tslibVersion,
+      typescript: typescriptVersion,
     },
   };
 }
@@ -42,7 +42,9 @@ function rootTsconfigJson() {
     compilerOptions: {
       target: 'ES2022',
       module: 'ES2022',
-      moduleResolution: 'Node',
+      // Angular >=21 relies on modern package exports resolution for some subpaths
+      // (e.g. @angular/common/http, @angular/core/rxjs-interop).
+      moduleResolution: 'bundler',
       lib: ['ES2022', 'DOM'],
       strict: true,
       skipLibCheck: true,
@@ -63,9 +65,18 @@ export async function ensureStandaloneWorkspace({ repoRoot, log }) {
   await ensureDir(distRoot);
   await ensureDir(workspaceRoot);
 
-  const angularVersion = (await detectAngularVersion(repoRoot)) ?? '20.1.7';
+  const detected = await detectToolchainVersions(repoRoot);
+  const angularVersion = detected.angularVersion ?? '21.1.4';
+  const derived = deriveToolchainDefaultsFromAngular(angularVersion);
+  const ngPackagrVersion = detected.ngPackagrVersion ?? derived.ngPackagrVersion;
+  const typescriptVersion = detected.typescriptVersion ?? derived.typescriptVersion;
+  const rxjsVersion = detected.rxjsVersion ?? '7.8.2';
+  const tslibVersion = detected.tslibVersion ?? '2.8.1';
   log?.debug?.('[meridiane] angular version', { angularVersion });
-  await writeJsonIfChanged(path.join(workspaceRoot, 'package.json'), toolchainPackageJson({ angularVersion }));
+  await writeJsonIfChanged(
+    path.join(workspaceRoot, 'package.json'),
+    toolchainPackageJson({ angularVersion, ngPackagrVersion, typescriptVersion, rxjsVersion, tslibVersion })
+  );
   await writeJsonIfChanged(path.join(workspaceRoot, 'tsconfig.json'), rootTsconfigJson());
 
   const npmCacheDir = path.join(workspaceRoot, '.npm-cache');
@@ -76,21 +87,44 @@ export async function ensureStandaloneWorkspace({ repoRoot, log }) {
   return { workspaceRoot, distRoot, npmCacheDir, requireFromWs };
 }
 
-async function detectAngularVersion(repoRoot) {
+async function detectToolchainVersions(repoRoot) {
   const pkgPath = path.join(repoRoot, 'package.json');
   try {
     const raw = await fs.readFile(pkgPath, 'utf8');
     const parsed = JSON.parse(raw);
-    const deps = parsed?.dependencies || {};
-    const devDeps = parsed?.devDependencies || {};
-    const peerDeps = parsed?.peerDependencies || {};
-    const v = deps['@angular/core'] ?? devDeps['@angular/core'] ?? peerDeps['@angular/core'];
-    return typeof v === 'string' && v.trim().length > 0 ? v.trim() : undefined;
+    const angularVersion = readDependencyVersion(parsed, '@angular/core');
+    const ngPackagrVersion = readDependencyVersion(parsed, 'ng-packagr');
+    const typescriptVersion = readDependencyVersion(parsed, 'typescript');
+    const rxjsVersion = readDependencyVersion(parsed, 'rxjs');
+    const tslibVersion = readDependencyVersion(parsed, 'tslib');
+    return { angularVersion, ngPackagrVersion, typescriptVersion, rxjsVersion, tslibVersion };
   } catch {
-    return undefined;
+    return {};
   }
 }
 
+function readDependencyVersion(pkg, depName) {
+  const deps = pkg?.dependencies || {};
+  const devDeps = pkg?.devDependencies || {};
+  const peerDeps = pkg?.peerDependencies || {};
+  const value = deps[depName] ?? devDeps[depName] ?? peerDeps[depName];
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function deriveToolchainDefaultsFromAngular(angularVersion) {
+  const major = parseInt(String(angularVersion).match(/\d+/)?.[0] ?? '0', 10);
+  if (major >= 21) {
+    return {
+      ngPackagrVersion: '21.1.0',
+      typescriptVersion: '5.9.3',
+    };
+  }
+  return {
+    ngPackagrVersion: '20.1.0',
+    typescriptVersion: '5.8.3',
+  };
+}
+
 export async function ensureToolchainInstalled({ workspaceRoot, requireFromWs, npmCacheDir, log }) {
   // Prefer using existing (hoisted) deps during local dev; in CI this will trigger installation.
   const canResolve = (id) => {