@zhin.js/runtime 1.1.1 → 1.1.3

package/lib/hmr-coordinator.js

@@ -21,7 +21,7 @@ export class HmrCoordinator {
         if (!this.options.modules.watch) {
             throw new Error('ModuleRuntime does not provide a file watcher');
         }
-        this.#syncWatchRoots();
+        this.#syncModuleState();
         this.#unwatch = this.options.modules.watch((source) => {
             void this.enqueue(source).catch(() => undefined);
         });
@@ -99,21 +99,23 @@ export class HmrCoordinator {
                 if (plan.kind === 'none')
                     continue;
                 const startedAt = performance.now();
-                for (const source of plan.changed) {
-                    await this.options.modules.invalidate?.(source);
-                }
-                const restart = await this.options.runtime.reload(plan);
-                if (restart) {
-                    this.#restartRequired = true;
-                    this.#pending.clear();
-                    this.#notifyRestart(restart);
-                    break;
-                }
-                else {
+                try {
+                    this.options.modules.beginGeneration?.();
+                    for (const source of plan.changed) {
+                        await this.options.modules.invalidate?.(source);
+                    }
+                    const restart = await this.options.runtime.reload(plan);
+                    if (restart) {
+                        this.options.modules.rollbackGeneration?.();
+                        this.#restartRequired = true;
+                        this.#pending.clear();
+                        this.#notifyRestart(restart);
+                        break;
+                    }
                     // reload resolves only after RootController has committed the new
-                    // generation. Read ownership now so failed transactions never make
-                    // newly discovered workspace packages observable to the watcher.
-                    this.#syncWatchRoots();
+                    // generation. Commit module metadata and ownership together so a
+                    // failed transaction keeps the previous dependency graph intact.
+                    this.#syncModuleState();
                     const durationMs = Number((performance.now() - startedAt).toFixed(1));
                     try {
                         await this.options.onReload?.(plan, durationMs);
@@ -128,6 +130,10 @@ export class HmrCoordinator {
                         }
                     }
                 }
+                catch (error) {
+                    this.options.modules.rollbackGeneration?.();
+                    throw error;
+                }
             }
             this.#resolveWaiters();
         }
@@ -158,8 +164,10 @@ export class HmrCoordinator {
         for (const waiter of this.#waiters.splice(0))
             waiter.reject(error);
     }
-    #syncWatchRoots() {
-        this.options.modules.updateWatchRoots?.(this.options.ownership().watchRoots());
+    #syncModuleState() {
+        const ownership = this.options.ownership();
+        this.options.modules.updateWatchRoots?.(ownership.watchRoots());
+        this.options.modules.commitGeneration?.(ownership.moduleSources());
     }
     #notifyRestart(plan) {
         // Restart is a committed control outcome. Invoke the observer without

package/lib/module-dependency-index.d.ts

@@ -0,0 +1,17 @@
+export interface ModuleDependencyAnalysis {
+    readonly dependencies: ReadonlySet<string>;
+    readonly commonJsSources: ReadonlySet<string>;
+}
+/** Tracks the local import closure of every module entry loaded by the runtime. */
+export declare class ModuleDependencyIndex {
+    #private;
+    analyze(entry: string): Promise<ModuleDependencyAnalysis>;
+    commit(entry: string, result: ModuleDependencyAnalysis): void;
+    /** Marks the changed entry and every entry importing it for lazy re-analysis. */
+    invalidate(source: string): void;
+    /** Drops entries that no longer belong to the successfully committed generation. */
+    retain(entries: readonly string[]): void;
+    clear(): void;
+    hasCommonJsImpact(source: string): boolean;
+    affectedSources(source: string): readonly string[];
+}

package/lib/module-dependency-index.js

@@ -0,0 +1,402 @@
+import { access, readFile } from 'node:fs/promises';
+import { basename, dirname, extname, isAbsolute, join, relative, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { init, parse } from 'es-module-lexer';
+import { resolve as resolveImport } from 'import-meta-resolve';
+const executableExtensions = Object.freeze([
+    '.cjs', '.cts', '.js', '.jsx', '.mjs', '.mts', '.ts', '.tsx',
+]);
+const sourceAlternatives = Object.freeze({
+    '.js': Object.freeze(['.ts', '.tsx', '.mts', '.cts', '.js']),
+    '.jsx': Object.freeze(['.tsx', '.jsx']),
+    '.cjs': Object.freeze(['.cts', '.cjs']),
+    '.mjs': Object.freeze(['.mts', '.mjs']),
+});
+/** Tracks the local import closure of every module entry loaded by the runtime. */
+export class ModuleDependencyIndex {
+    #dependenciesByEntry = new Map();
+    #entriesByDependency = new Map();
+    #commonJsSourcesByEntry = new Map();
+    #entriesByCommonJsSource = new Map();
+    #commonJsByDirectory = new Map();
+    #dirtyEntries = new Set();
+    async analyze(entry) {
+        const normalized = resolve(entry);
+        const cached = this.#dependenciesByEntry.get(normalized);
+        if (cached && !this.#dirtyEntries.has(normalized)) {
+            return analysis(cached, this.#commonJsSourcesByEntry.get(normalized) ?? new Set());
+        }
+        await init;
+        const dependencies = new Set();
+        const commonJsSources = new Set();
+        const visited = new Set();
+        await this.#visit(normalized, normalized, dependencies, commonJsSources, visited);
+        return analysis(dependencies, commonJsSources);
+    }
+    commit(entry, result) {
+        const normalized = resolve(entry);
+        this.#remove(normalized);
+        const dependencies = new Set(result.dependencies);
+        const commonJsSources = new Set(result.commonJsSources);
+        this.#dependenciesByEntry.set(normalized, dependencies);
+        this.#commonJsSourcesByEntry.set(normalized, commonJsSources);
+        this.#dirtyEntries.delete(normalized);
+        for (const dependency of dependencies) {
+            addReverseEntry(this.#entriesByDependency, dependency, normalized);
+        }
+        for (const source of commonJsSources) {
+            addReverseEntry(this.#entriesByCommonJsSource, source, normalized);
+        }
+    }
+    /** Marks the changed entry and every entry importing it for lazy re-analysis. */
+    invalidate(source) {
+        const normalized = resolve(source);
+        if (basename(normalized) === 'package.json') {
+            this.#commonJsByDirectory.clear();
+            const packageRoot = dirname(normalized);
+            for (const [entry, dependencies] of this.#dependenciesByEntry) {
+                if (isWithin(packageRoot, entry)
+                    || [...dependencies].some((dependency) => isWithin(packageRoot, dependency))) {
+                    this.#dirtyEntries.add(entry);
+                }
+            }
+        }
+        if (this.#dependenciesByEntry.has(normalized))
+            this.#dirtyEntries.add(normalized);
+        for (const entry of this.#entriesByDependency.get(normalized) ?? []) {
+            this.#dirtyEntries.add(entry);
+        }
+    }
+    /** Drops entries that no longer belong to the successfully committed generation. */
+    retain(entries) {
+        const active = new Set(entries.map((entry) => resolve(entry)));
+        for (const entry of this.#dependenciesByEntry.keys()) {
+            if (!active.has(entry))
+                this.#remove(entry);
+        }
+    }
+    clear() {
+        this.#dependenciesByEntry.clear();
+        this.#entriesByDependency.clear();
+        this.#commonJsSourcesByEntry.clear();
+        this.#entriesByCommonJsSource.clear();
+        this.#commonJsByDirectory.clear();
+        this.#dirtyEntries.clear();
+    }
+    hasCommonJsImpact(source) {
+        const normalized = resolve(source);
+        if (isExplicitCommonJsSource(normalized))
+            return true;
+        if (this.#entriesByCommonJsSource.has(normalized))
+            return true;
+        return [...(this.#entriesByDependency.get(normalized) ?? [])].some((entry) => this.#commonJsSourcesByEntry.get(entry)?.has(entry) ?? false);
+    }
+    affectedSources(source) {
+        const normalized = resolve(source);
+        const entries = [...(this.#entriesByDependency.get(normalized) ?? [])].sort();
+        return Object.freeze([normalized, ...entries.filter((entry) => entry !== normalized)]);
+    }
+    #remove(entry) {
+        for (const dependency of this.#dependenciesByEntry.get(entry) ?? []) {
+            removeReverseEntry(this.#entriesByDependency, dependency, entry);
+        }
+        for (const source of this.#commonJsSourcesByEntry.get(entry) ?? []) {
+            removeReverseEntry(this.#entriesByCommonJsSource, source, entry);
+        }
+        this.#dependenciesByEntry.delete(entry);
+        this.#commonJsSourcesByEntry.delete(entry);
+        this.#dirtyEntries.delete(entry);
+    }
+    async #visit(entry, source, dependencies, commonJsSources, visited) {
+        if (visited.has(source))
+            return;
+        visited.add(source);
+        if (source !== entry)
+            dependencies.add(source);
+        if (!executableExtensions.includes(extname(source)))
+            return;
+        let text;
+        try {
+            text = await readFile(source, 'utf8');
+        }
+        catch {
+            return;
+        }
+        const commonJs = await this.#isCommonJsSource(source);
+        if (commonJs)
+            commonJsSources.add(source);
+        const specifiers = commonJs ? commonJsSpecifiers(text) : [];
+        try {
+            const [imports] = parse(text, source);
+            specifiers.push(...imports.flatMap((imported) => imported.n ? [imported.n] : []));
+        }
+        catch {
+            // Import analysis is an HMR optimization. Module loading remains the
+            // authority for syntax diagnostics and must not be hidden by the index.
+            // CommonJS requires were already collected by the tolerant lexer above.
+            if (!commonJs)
+                return;
+        }
+        for (const specifier of specifiers) {
+            const dependency = await resolveLocalImport(source, specifier);
+            if (dependency) {
+                await this.#visit(entry, dependency, dependencies, commonJsSources, visited);
+            }
+        }
+    }
+    #isCommonJsSource(source) {
+        if (isExplicitCommonJsSource(source))
+            return Promise.resolve(true);
+        if (['.mjs', '.mts'].includes(extname(source)))
+            return Promise.resolve(false);
+        const directory = dirname(source);
+        const cached = this.#commonJsByDirectory.get(directory);
+        if (cached)
+            return cached;
+        const detected = findCommonJsPackage(directory);
+        this.#commonJsByDirectory.set(directory, detected);
+        return detected;
+    }
+}
+function analysis(dependencies, commonJsSources) {
+    return Object.freeze({ dependencies, commonJsSources });
+}
+function addReverseEntry(index, source, entry) {
+    const entries = index.get(source) ?? new Set();
+    entries.add(entry);
+    index.set(source, entries);
+}
+function removeReverseEntry(index, source, entry) {
+    const entries = index.get(source);
+    entries?.delete(entry);
+    if (entries?.size === 0)
+        index.delete(source);
+}
+/** Collects literal require()/require.resolve() calls outside comments and literal text. */
+function commonJsSpecifiers(source) {
+    const specifiers = [];
+    let index = 0;
+    while (index < source.length) {
+        const character = source[index];
+        if (character === '"' || character === "'") {
+            index = skipQuoted(source, index, character);
+            continue;
+        }
+        if (character === '`') {
+            index = skipTemplate(source, index);
+            continue;
+        }
+        if (character === '/' && source[index + 1] === '/') {
+            index = skipLineComment(source, index + 2);
+            continue;
+        }
+        if (character === '/' && source[index + 1] === '*') {
+            index = skipBlockComment(source, index + 2);
+            continue;
+        }
+        if (!isIdentifierStart(character)) {
+            index += 1;
+            continue;
+        }
+        const start = index;
+        index = skipIdentifier(source, index + 1);
+        if (source.slice(start, index) !== 'require' || previousSignificant(source, start) === '.') {
+            continue;
+        }
+        const call = readRequireCall(source, index);
+        if (!call)
+            continue;
+        specifiers.push(call.specifier);
+        index = call.end;
+    }
+    return specifiers;
+}
+function readRequireCall(source, start) {
+    let index = skipTrivia(source, start);
+    if (source[index] === '.') {
+        index = skipTrivia(source, index + 1);
+        const identifierStart = index;
+        index = skipIdentifier(source, index);
+        if (source.slice(identifierStart, index) !== 'resolve')
+            return undefined;
+        index = skipTrivia(source, index);
+    }
+    if (source[index] !== '(')
+        return undefined;
+    index = skipTrivia(source, index + 1);
+    const quote = source[index];
+    if (quote !== '"' && quote !== "'")
+        return undefined;
+    const literal = readStringLiteral(source, index, quote);
+    if (!literal)
+        return undefined;
+    index = skipTrivia(source, literal.end);
+    if (source[index] !== ')')
+        return undefined;
+    return { specifier: literal.value, end: index + 1 };
+}
+function readStringLiteral(source, start, quote) {
+    let value = '';
+    let index = start + 1;
+    while (index < source.length) {
+        const character = source[index];
+        if (character === quote)
+            return { value, end: index + 1 };
+        if (character === '\\') {
+            const escaped = source[index + 1];
+            if (!escaped || escaped === '\n' || escaped === '\r')
+                return undefined;
+            value += escaped;
+            index += 2;
+            continue;
+        }
+        if (character === '\n' || character === '\r')
+            return undefined;
+        value += character;
+        index += 1;
+    }
+    return undefined;
+}
+function skipTrivia(source, start) {
+    let index = start;
+    while (index < source.length) {
+        if (/\s/u.test(source[index] ?? '')) {
+            index += 1;
+        }
+        else if (source[index] === '/' && source[index + 1] === '/') {
+            index = skipLineComment(source, index + 2);
+        }
+        else if (source[index] === '/' && source[index + 1] === '*') {
+            index = skipBlockComment(source, index + 2);
+        }
+        else {
+            break;
+        }
+    }
+    return index;
+}
+function skipQuoted(source, start, quote) {
+    let index = start + 1;
+    while (index < source.length) {
+        if (source[index] === '\\')
+            index += 2;
+        else if (source[index] === quote)
+            return index + 1;
+        else
+            index += 1;
+    }
+    return source.length;
+}
+function skipTemplate(source, start) {
+    let index = start + 1;
+    while (index < source.length) {
+        if (source[index] === '\\')
+            index += 2;
+        else if (source[index] === '`')
+            return index + 1;
+        else
+            index += 1;
+    }
+    return source.length;
+}
+function skipLineComment(source, start) {
+    const end = source.indexOf('\n', start);
+    return end < 0 ? source.length : end + 1;
+}
+function skipBlockComment(source, start) {
+    const end = source.indexOf('*/', start);
+    return end < 0 ? source.length : end + 2;
+}
+function isIdentifierStart(character) {
+    return character !== undefined && /[A-Za-z_$]/u.test(character);
+}
+function skipIdentifier(source, start) {
+    let index = start;
+    while (/[\w$]/u.test(source[index] ?? ''))
+        index += 1;
+    return index;
+}
+function previousSignificant(source, start) {
+    let index = start - 1;
+    while (index >= 0 && /\s/u.test(source[index] ?? ''))
+        index -= 1;
+    return source[index];
+}
+function isExplicitCommonJsSource(source) {
+    return ['.cjs', '.cts'].includes(extname(source));
+}
+async function findCommonJsPackage(start) {
+    let directory = start;
+    while (true) {
+        try {
+            const manifest = JSON.parse(await readFile(join(directory, 'package.json'), 'utf8'));
+            return manifest.type !== 'module';
+        }
+        catch {
+            const parent = dirname(directory);
+            if (parent === directory)
+                return true;
+            directory = parent;
+        }
+    }
+}
+async function resolveLocalImport(importer, specifier) {
+    let requested;
+    try {
+        if (specifier.startsWith('file:'))
+            requested = fileURLToPath(specifier);
+        else if (isAbsolute(specifier))
+            requested = specifier;
+        else if (specifier.startsWith('.'))
+            requested = resolve(dirname(importer), specifier);
+        else if (specifier.startsWith('#')) {
+            const resolvedImport = resolveImport(specifier, pathToFileURL(importer).href);
+            if (resolvedImport.startsWith('node:'))
+                return undefined;
+            requested = fileURLToPath(resolvedImport);
+        }
+        else
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    for (const candidate of importCandidates(requested)) {
+        if (await exists(candidate))
+            return resolve(candidate);
+    }
+    return undefined;
+}
+function importCandidates(requested) {
+    const extension = extname(requested);
+    if (extension) {
+        const alternatives = sourceAlternatives[extension];
+        if (!alternatives)
+            return [requested];
+        const stem = requested.slice(0, -extension.length);
+        return [
+            requested,
+            ...alternatives
+                .filter((candidate) => candidate !== extension)
+                .map((candidate) => `${stem}${candidate}`),
+        ];
+    }
+    return [
+        requested,
+        ...executableExtensions.map((candidate) => `${requested}${candidate}`),
+        ...executableExtensions.map((candidate) => resolve(requested, `index${candidate}`)),
+    ];
+}
+function isWithin(root, source) {
+    const child = relative(root, source);
+    return child === '' || (!child.startsWith('..') && !isAbsolute(child));
+}
+async function exists(source) {
+    try {
+        await access(source);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/lib/module-runtime.d.ts

@@ -12,6 +12,12 @@ export interface ModuleRuntime {
     affectedSources?(source: string): readonly string[];
     /** True when this adapter cannot invalidate the complete importer closure safely. */
     requiresProcessRestart?(source: string): boolean;
+    /** Starts staging module metadata for a generation transaction. */
+    beginGeneration?(): void;
+    /** Commits staged metadata and the active module set after the generation commits. */
+    commitGeneration?(sources: readonly string[]): void;
+    /** Discards metadata staged by a failed generation transaction. */
+    rollbackGeneration?(): void;
     /** Replaces the local package roots after a generation commits. */
     updateWatchRoots?(roots: readonly ModuleWatchRoot[]): void;
     watch?(listener: (source: string) => void): Dispose;

package/lib/native-development-runtime.d.ts

@@ -3,18 +3,27 @@ import type { ModuleRuntime, ModuleWatchRoot } from './module-runtime.js';
 export interface NativeDevelopmentModuleRuntimeOptions {
     readonly projectRoot: string;
     readonly watch?: boolean;
+    /** Optional scoped loader used only when the active Node loader rejects TSX. */
+    readonly tsxLoader?: TsxModuleLoader;
+}
+export interface TsxModuleLoader {
+    load<T = unknown>(source: string, parentURL: string): Promise<T>;
+    close?(): Promise<void>;
 }
 /**
- * Uses Node's native ESM/TypeScript loader and adds only cache busting and watch.
- * It deliberately requests a process restart for support modules whose cached
- * relative import closure cannot be invalidated without a custom loader.
+ * Uses Node's native ESM/TypeScript loader with dependency-aware cache busting
+ * and portable filesystem watch support.
  */
 export declare class NativeDevelopmentModuleRuntime implements ModuleRuntime {
     #private;
     constructor(options: NativeDevelopmentModuleRuntimeOptions);
     load<T = unknown>(source: string): Promise<T>;
     invalidate(source: string): void;
+    affectedSources(source: string): readonly string[];
     requiresProcessRestart(source: string): boolean;
+    beginGeneration(): void;
+    commitGeneration(sources: readonly string[]): void;
+    rollbackGeneration(): void;
     updateWatchRoots(roots: readonly ModuleWatchRoot[]): void;
     watch(listener: (source: string) => void): Dispose;
     close(): Promise<void>;

package/lib/native-development-runtime.js

@@ -1,47 +1,70 @@
 import { readdirSync, statSync, watch as watchDirectory, } from 'node:fs';
 import { basename, extname, isAbsolute, relative, resolve, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { ModuleDependencyIndex, } from './module-dependency-index.js';
+import { ensureTypeScriptSpecifierRemap } from './typescript-specifier-remap.js';
 const ignoredDirectories = new Set([
     '.git', '.zhin', 'coverage', 'data', 'dist', 'lib', 'node_modules',
 ]);
 const watchedExtensions = new Set([
-    '.cjs', '.js', '.json', '.md', '.mjs', '.ts', '.tsx', '.yaml', '.yml',
+    '.cjs', '.cts', '.js', '.json', '.jsx', '.md', '.mjs', '.mts',
+    '.ts', '.tsx', '.yaml', '.yml',
 ]);
 const capabilityRoots = new Set([
     'adapters', 'agents', 'commands', 'components', 'handlers', 'hooks', 'mcps', 'middlewares', 'pages', 'prompt-sections', 'schedules', 'skills', 'tools',
 ]);
 /**
- * Uses Node's native ESM/TypeScript loader and adds only cache busting and watch.
- * It deliberately requests a process restart for support modules whose cached
- * relative import closure cannot be invalidated without a custom loader.
+ * Uses Node's native ESM/TypeScript loader with dependency-aware cache busting
+ * and portable filesystem watch support.
  */
 export class NativeDevelopmentModuleRuntime {
     #projectRoot;
     #watchEnabled;
-    #revisions = new Map();
+    #tsxLoader;
+    #dependencies = new ModuleDependencyIndex();
     #watchers = new Set();
+    #pendingDependencies;
     #watchRoots;
+    #revision = 0;
     #closed = false;
     constructor(options) {
+        ensureTypeScriptSpecifierRemap();
         this.#projectRoot = resolve(options.projectRoot);
         this.#watchEnabled = options.watch ?? true;
+        this.#tsxLoader = options.tsxLoader;
         this.#watchRoots = normalizeWatchRoots([this.#projectRoot]);
     }
     async load(source) {
         this.#assertOpen();
         const normalized = resolve(source);
-        if (normalized.endsWith('.tsx')) {
-            throw new Error(`Node native TypeScript does not support TSX: ${normalized}`);
-        }
-        if (normalized.endsWith('.ts'))
+        if (isNativeTypeScriptSource(normalized))
             assertNativeTypeScriptSupport();
+        const analysis = this.#pendingDependencies?.get(normalized)
+            ?? await this.#dependencies.analyze(normalized);
         const url = pathToFileURL(normalized);
-        url.searchParams.set('zhin-generation', String(this.#revisions.get(normalized) ?? 0));
-        return import(url.href);
+        url.searchParams.set('zhin-generation', String(this.#revision));
+        let loaded;
+        try {
+            loaded = await import(url.href);
+        }
+        catch (error) {
+            if (!normalized.endsWith('.tsx') || !isUnsupportedTsxError(error) || !this.#tsxLoader) {
+                throw error;
+            }
+            loaded = await this.#tsxLoader.load(url.href, pathToFileURL(`${this.#projectRoot}${sep}`).href);
+        }
+        if (this.#pendingDependencies)
+            this.#pendingDependencies.set(normalized, analysis);
+        else
+            this.#dependencies.commit(normalized, analysis);
+        return loaded;
     }
     invalidate(source) {
-        const normalized = resolve(source);
-        this.#revisions.set(normalized, (this.#revisions.get(normalized) ?? 0) + 1);
+        this.#dependencies.invalidate(source);
+        this.#revision += 1;
+    }
+    affectedSources(source) {
+        return this.#dependencies.affectedSources(source);
     }
     requiresProcessRestart(source) {
         const normalized = resolve(source);
@@ -52,6 +75,16 @@ export class NativeDevelopmentModuleRuntime {
             return true;
         if (packageRoot === this.#projectRoot && basename(normalized).startsWith('.env'))
             return true;
+        // Native ESM query revisions do not invalidate CommonJS require.cache.
+        // Keep .cjs/.cts entries and their statically discovered closure on the
+        // process boundary until the module runtime owns a CJS cache transaction.
+        if (this.#dependencies.hasCommonJsImpact(normalized))
+            return true;
+        // A helper with one or more loaded entry importers is safe: the planner
+        // invalidates those owned entries and the generation query refreshes their
+        // complete project-local import closure.
+        if (this.affectedSources(normalized).length > 1)
+            return false;
         const parts = relative(packageRoot, normalized).split(sep);
         const capability = parts.findIndex((part) => capabilityRoots.has(part));
         if (capability < 0)
@@ -83,7 +116,26 @@ export class NativeDevelopmentModuleRuntime {
         // Support files inside capability directories (e.g. commands/_utils.ts)
         // are not discovery entries: reloading the entry URL only bumps that
         // entry's zhin-generation, so the importer closure keeps the old code.
-        return ['.js', '.json', '.ts'].includes(extname(normalized));
+        return ['.cjs', '.cts', '.js', '.json', '.mjs', '.mts', '.ts', '.tsx']
+            .includes(extname(normalized));
+    }
+    beginGeneration() {
+        this.#assertOpen();
+        if (this.#pendingDependencies) {
+            throw new Error('A module generation transaction is already active');
+        }
+        this.#pendingDependencies = new Map();
+    }
+    commitGeneration(sources) {
+        this.#assertOpen();
+        for (const [entry, analysis] of this.#pendingDependencies ?? []) {
+            this.#dependencies.commit(entry, analysis);
+        }
+        this.#pendingDependencies = undefined;
+        this.#dependencies.retain(sources);
+    }
+    rollbackGeneration() {
+        this.#pendingDependencies = undefined;
     }
     updateWatchRoots(roots) {
         this.#assertOpen();
@@ -115,6 +167,9 @@ export class NativeDevelopmentModuleRuntime {
         for (const watcher of this.#watchers)
             watcher.close();
         this.#watchers.clear();
+        this.#pendingDependencies = undefined;
+        this.#dependencies.clear();
+        await this.#tsxLoader?.close?.();
     }
     #assertOpen() {
         if (this.#closed)
@@ -134,7 +189,7 @@ function isNamedCapabilityDirectory(value, allowSnake) {
 function isDirectoryCapabilityEntry(parts) {
     return parts.length === 2
         && parts[1] === `index${extname(parts[1] ?? '')}`
-        && ['.cjs', '.js', '.mjs', '.ts'].includes(extname(parts[1] ?? ''));
+        && ['.cjs', '.cts', '.js', '.mjs', '.mts', '.ts', '.tsx'].includes(extname(parts[1] ?? ''));
 }
 function isNestedDirectoryEntry(parts) {
     const index = parts.indexOf('tools');
@@ -157,6 +212,11 @@ export function assertNativeTypeScriptSupport() {
         'Use Node >=22.18.0 or start Node with --experimental-strip-types.',
     ].join(' '));
 }
+function isUnsupportedTsxError(error) {
+    return error instanceof Error
+        && 'code' in error
+        && error.code === 'ERR_UNKNOWN_FILE_EXTENSION';
+}
 class PortableSourceWatcher {
     listener;
     #watchers = new Set();
@@ -277,7 +337,10 @@ function isIgnoredSource(root, source) {
     return relative(root, source).split(sep).some((segment) => ignoredDirectories.has(segment));
 }
 function isExecutableSource(source) {
-    return ['.cjs', '.js', '.mjs', '.ts', '.tsx'].includes(extname(source));
+    return ['.cjs', '.cts', '.js', '.mjs', '.mts', '.ts', '.tsx'].includes(extname(source));
+}
+function isNativeTypeScriptSource(source) {
+    return ['.cts', '.mts', '.ts'].includes(extname(source));
 }
 function isWithin(root, source) {
     const child = relative(root, source);

package/lib/source-ownership.d.ts

@@ -17,6 +17,7 @@ export declare class SourceOwnershipIndex {
     addPackageRoot(packageRoot: string, owner: PluginId): void;
     recordsFor(source: string): readonly SourceOwnershipRecord[];
     ownersForPath(source: string): readonly PluginId[];
+    moduleSources(): readonly string[];
     watchRoots(): readonly ModuleWatchRoot[];
     addWatchRoot(root: ModuleWatchRoot): void;
 }

package/lib/source-ownership.js

@@ -92,6 +92,12 @@ export class SourceOwnershipIndex {
         }
         return Object.freeze([...owners]);
     }
+    moduleSources() {
+        return Object.freeze([...this.#records.entries()]
+            .filter(([, records]) => records.some((record) => (record.role === 'plugin' || record.role === 'feature' || record.role === 'capability')))
+            .map(([source]) => source)
+            .sort());
+    }
     watchRoots() {
         return Object.freeze([...this.#watchRoots.values()]);
     }

package/lib/typescript-specifier-remap.d.ts

@@ -1,3 +1,8 @@
+interface ResolveResult {
+    readonly url: string;
+    readonly shortCircuit?: boolean;
+    readonly format?: string;
+}
 /**
  * ESM resolve hook: when a relative/absolute `.js` specifier fails and a
  * sibling `.ts` / `.tsx` exists, rewrite to that source file.
@@ -10,14 +15,7 @@ export declare function resolve(specifier: string, context: {
     parentURL?: string;
 }, nextResolve: (specifier: string, context: {
     parentURL?: string;
-}) => Promise<{
-    url: string;
-    shortCircuit?: boolean;
-    format?: string;
-}>): Promise<{
-    url: string;
-    shortCircuit?: boolean;
-    format?: string;
-}>;
+}) => Promise<ResolveResult>): Promise<ResolveResult>;
 /** Register once for the current process (safe to call from CLI / RootHost). */
 export declare function ensureTypeScriptSpecifierRemap(): void;
+export {};

package/lib/typescript-specifier-remap.js

@@ -1,6 +1,6 @@
 import { access } from 'node:fs/promises';
 import { register } from 'node:module';
-import { sep } from 'node:path';
+import { isAbsolute, sep } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 /**
  * ESM resolve hook: when a relative/absolute `.js` specifier fails and a
@@ -11,8 +11,9 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
  * remap missing `.js` → `.ts` the way `tsc`/tsx do.
  */
 export async function resolve(specifier, context, nextResolve) {
+    let resolved;
     try {
-        return await nextResolve(specifier, context);
+        resolved = await nextResolve(specifier, context);
     }
     catch (error) {
         if (!shouldTryTypeScript(specifier, error))
@@ -20,8 +21,9 @@ export async function resolve(specifier, context, nextResolve) {
         const candidate = await firstExistingTypeScript(specifier, context.parentURL);
         if (!candidate)
             throw error;
-        return nextResolve(candidate, context);
+        resolved = await nextResolve(candidate, context);
     }
+    return inheritGenerationRevision(specifier, context.parentURL, resolved);
 }
 let registered = false;
 /** Register once for the current process (safe to call from CLI / RootHost). */
@@ -39,6 +41,29 @@ function shouldTryTypeScript(specifier, error) {
         return false;
     return /\.[cm]?js$/u.test(specifier) || specifier.endsWith('.jsx');
 }
+function inheritGenerationRevision(specifier, parentURL, resolved) {
+    if (!parentURL || !isLocalSpecifier(specifier) || !resolved.url.startsWith('file:')) {
+        return resolved;
+    }
+    let revision;
+    try {
+        revision = new URL(parentURL).searchParams.get('zhin-generation');
+    }
+    catch {
+        return resolved;
+    }
+    if (revision === null)
+        return resolved;
+    const url = new URL(resolved.url);
+    url.searchParams.set('zhin-generation', revision);
+    return { ...resolved, url: url.href };
+}
+function isLocalSpecifier(specifier) {
+    return specifier.startsWith('.')
+        || specifier.startsWith('#')
+        || specifier.startsWith('file:')
+        || isAbsolute(specifier);
+}
 async function firstExistingTypeScript(specifier, parentURL) {
     const resolvedJs = resolveAgainstParent(specifier, parentURL);
     if (!resolvedJs)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/runtime",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "description": "Static Plugin graph, generation transaction and HMR Root runtime for Zhin.js",
   "type": "module",
   "main": "./lib/index.js",
@@ -17,24 +17,27 @@
   ],
   "dependencies": {
     "ajv": "8.18.0",
+    "es-module-lexer": "2.3.1",
+    "import-meta-resolve": "4.2.0",
     "semver": "7.8.5",
-    "@zhin.js/feature-kit": "1.1.1",
-    "@zhin.js/plugin-runtime": "1.1.10"
+    "@zhin.js/feature-kit": "1.1.2",
+    "@zhin.js/plugin-runtime": "1.1.11"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
+    "tsx": "^4.23.1",
     "typescript": "^6.0.3",
-    "@zhin.js/adapter": "1.1.14",
-    "@zhin.js/agent-feature": "1.1.1",
-    "@zhin.js/command": "1.1.1",
-    "@zhin.js/component": "1.1.1",
-    "@zhin.js/layout": "1.1.1",
-    "@zhin.js/mcp-feature": "1.1.1",
-    "@zhin.js/middleware": "1.1.1",
-    "@zhin.js/page": "1.1.1",
-    "@zhin.js/prompt-section": "1.1.1",
-    "@zhin.js/skill": "1.1.1",
-    "@zhin.js/tool": "1.1.1"
+    "@zhin.js/adapter": "1.1.15",
+    "@zhin.js/agent-feature": "1.1.2",
+    "@zhin.js/command": "1.1.3",
+    "@zhin.js/component": "1.1.2",
+    "@zhin.js/layout": "1.1.3",
+    "@zhin.js/mcp-feature": "1.1.2",
+    "@zhin.js/middleware": "1.1.2",
+    "@zhin.js/prompt-section": "1.1.2",
+    "@zhin.js/page": "1.1.3",
+    "@zhin.js/tool": "1.1.2",
+    "@zhin.js/skill": "1.1.2"
   },
   "repository": {
     "type": "git",