@xdelivered/emberflow 0.4.0 → 0.5.0

package/dist/server/sourceNav.js

@@ -0,0 +1,503 @@
+import { readFileSync, statSync } from 'node:fs';
+import { promises as fsp } from 'node:fs';
+import { builtinModules } from 'node:module';
+import { dirname, extname, isAbsolute, join, relative, resolve } from 'node:path';
+import { isPathWithin } from './pathSafety.js';
+// ---------------------------------------------------------------------------
+// Lazy typescript module
+let tsModulePromise;
+async function loadTs(loader) {
+    if (loader) {
+        try {
+            return await loader();
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (!tsModulePromise) {
+        tsModulePromise = import('typescript').then((m) => (m.default ?? m));
+    }
+    try {
+        return await tsModulePromise;
+    }
+    catch {
+        tsModulePromise = undefined; // allow a later retry (e.g. install completed)
+        return undefined;
+    }
+}
+// ---------------------------------------------------------------------------
+// Path guards
+const TS_EXTS = new Set(['.ts', '.tsx', '.mts', '.cts']);
+function languageOf(file) {
+    return TS_EXTS.has(extname(file)) ? 'ts' : 'js';
+}
+/** Deny-list beyond isPathWithin: node_modules anywhere, secret basenames. */
+function isRequestPathAllowed(projectRoot, rel) {
+    if (!isPathWithin(projectRoot, rel))
+        return false;
+    const segments = rel.split('/');
+    if (segments.includes('node_modules'))
+        return false;
+    const base = (segments[segments.length - 1] ?? '').toLowerCase();
+    if (base.startsWith('.env'))
+        return false;
+    if (base === 'emberflow.secrets.json')
+        return false;
+    if (base.endsWith('.pem') || base.endsWith('.key'))
+        return false;
+    return true;
+}
+const parseCache = new Map();
+/** Clears all sourceNav caches (parse, tsconfig, ts module) — tests only. */
+export function resetSourceNavCaches() {
+    parseCache.clear();
+    tsconfigCache.clear();
+    tsModulePromise = undefined;
+}
+function scriptKindFor(ts, file) {
+    switch (extname(file)) {
+        case '.ts':
+        case '.mts':
+        case '.cts':
+            return ts.ScriptKind.TS;
+        case '.tsx':
+            return ts.ScriptKind.TSX;
+        case '.jsx':
+            return ts.ScriptKind.JSX;
+        default:
+            return ts.ScriptKind.JS;
+    }
+}
+function parseFile(ts, absPath, content) {
+    const sf = ts.createSourceFile(absPath, content, ts.ScriptTarget.Latest, 
+    /* setParentNodes */ true, scriptKindFor(ts, absPath));
+    const lineOf = (pos) => sf.getLineAndCharacterOfPosition(pos).line + 1;
+    const hasExportModifier = (node) => {
+        const mods = node.modifiers;
+        return !!mods?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+    };
+    const declarations = [];
+    const imports = [];
+    const reexports = [];
+    const dynamicImports = [];
+    /** Names exported post-hoc via a specifier-less `export { x }`. */
+    const localExports = new Set();
+    for (const stmt of sf.statements) {
+        if (ts.isFunctionDeclaration(stmt) && stmt.name) {
+            declarations.push({
+                name: stmt.name.text,
+                kind: 'fn',
+                line: lineOf(stmt.getStart(sf)),
+                endLine: lineOf(stmt.end),
+                exported: hasExportModifier(stmt),
+            });
+        }
+        else if (ts.isClassDeclaration(stmt) && stmt.name) {
+            declarations.push({
+                name: stmt.name.text,
+                kind: 'class',
+                line: lineOf(stmt.getStart(sf)),
+                endLine: lineOf(stmt.end),
+                exported: hasExportModifier(stmt),
+            });
+        }
+        else if (ts.isVariableStatement(stmt)) {
+            for (const decl of stmt.declarationList.declarations) {
+                if (ts.isIdentifier(decl.name) && decl.initializer) {
+                    declarations.push({
+                        name: decl.name.text,
+                        kind: 'const',
+                        line: lineOf(decl.getStart(sf)),
+                        endLine: lineOf(stmt.end),
+                        exported: hasExportModifier(stmt),
+                    });
+                }
+            }
+        }
+        else if (ts.isInterfaceDeclaration(stmt) ||
+            ts.isTypeAliasDeclaration(stmt) ||
+            ts.isEnumDeclaration(stmt)) {
+            declarations.push({
+                name: stmt.name.text,
+                kind: 'other',
+                line: lineOf(stmt.getStart(sf)),
+                endLine: lineOf(stmt.end),
+                exported: hasExportModifier(stmt),
+            });
+        }
+        else if (ts.isImportDeclaration(stmt) && ts.isStringLiteral(stmt.moduleSpecifier)) {
+            const from = stmt.moduleSpecifier.text;
+            const clause = stmt.importClause;
+            if (!clause) {
+                imports.push({ name: '*', local: '', from }); // side-effect import
+                continue;
+            }
+            if (clause.name)
+                imports.push({ name: 'default', local: clause.name.text, from });
+            const bindings = clause.namedBindings;
+            if (bindings) {
+                if (ts.isNamespaceImport(bindings)) {
+                    imports.push({ name: '*', local: bindings.name.text, from });
+                }
+                else {
+                    for (const el of bindings.elements) {
+                        imports.push({ name: (el.propertyName ?? el.name).text, local: el.name.text, from });
+                    }
+                }
+            }
+        }
+        else if (ts.isExportDeclaration(stmt)) {
+            const spec = stmt.moduleSpecifier;
+            if (spec && ts.isStringLiteral(spec)) {
+                const from = spec.text;
+                if (!stmt.exportClause) {
+                    reexports.push({ exported: '*', from });
+                }
+                else if (ts.isNamespaceExport(stmt.exportClause)) {
+                    reexports.push({ exported: stmt.exportClause.name.text, source: '*', from });
+                }
+                else {
+                    for (const el of stmt.exportClause.elements) {
+                        reexports.push({
+                            exported: el.name.text,
+                            source: (el.propertyName ?? el.name).text,
+                            from,
+                        });
+                    }
+                }
+            }
+            else if (stmt.exportClause && ts.isNamedExports(stmt.exportClause)) {
+                for (const el of stmt.exportClause.elements) {
+                    localExports.add((el.propertyName ?? el.name).text);
+                }
+            }
+        }
+    }
+    // `export { x }` after the declaration marks it exported.
+    for (const d of declarations) {
+        if (!d.exported && localExports.has(d.name))
+            d.exported = true;
+    }
+    // Dynamic imports live anywhere in the tree.
+    const visit = (node) => {
+        if (ts.isCallExpression(node) &&
+            node.expression.kind === ts.SyntaxKind.ImportKeyword) {
+            const arg = node.arguments[0];
+            dynamicImports.push(arg && ts.isStringLiteral(arg) ? { from: arg.text } : {});
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sf);
+    return { content, language: languageOf(absPath), declarations, imports, dynamicImports, reexports };
+}
+/** Parse (or reuse the cached parse of) an absolute path. Throws when unreadable. */
+function getParsed(ts, absPath) {
+    const stat = statSync(absPath);
+    const cached = parseCache.get(absPath);
+    if (cached && cached.mtimeMs === stat.mtimeMs)
+        return cached.parsed;
+    const content = readFileSync(absPath, 'utf8');
+    const parsed = parseFile(ts, absPath, content);
+    parseCache.set(absPath, { mtimeMs: stat.mtimeMs, parsed });
+    return parsed;
+}
+function getParsedSafe(ts, absPath) {
+    try {
+        return getParsed(ts, absPath);
+    }
+    catch {
+        return undefined;
+    }
+}
+// ---------------------------------------------------------------------------
+// Specifier resolution
+const RESOLVE_EXTS = ['.ts', '.tsx', '.mts', '.cts', '.js', '.mjs', '.cjs'];
+/** TS-style specifier mapping: an emitted-extension specifier may point at TS source. */
+const JS_TO_TS = {
+    '.js': ['.ts', '.tsx'],
+    '.mjs': ['.mts'],
+    '.cjs': ['.cts'],
+};
+function isFile(p) {
+    try {
+        return statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** Extension ladder: exact → +ext → TS .js→.ts mapping → /index.*  */
+function resolveWithLadder(base) {
+    if (isFile(base))
+        return base;
+    for (const ext of RESOLVE_EXTS) {
+        if (isFile(base + ext))
+            return base + ext;
+    }
+    for (const [jsExt, tsExts] of Object.entries(JS_TO_TS)) {
+        if (base.endsWith(jsExt)) {
+            const stem = base.slice(0, -jsExt.length);
+            for (const tsExt of tsExts) {
+                if (isFile(stem + tsExt))
+                    return stem + tsExt;
+            }
+        }
+    }
+    for (const ext of RESOLVE_EXTS) {
+        const idx = join(base, 'index' + ext);
+        if (isFile(idx))
+            return idx;
+    }
+    return undefined;
+}
+const tsconfigCache = new Map();
+function tsconfigPathsFor(ts, projectRoot) {
+    const cfgPath = join(projectRoot, 'tsconfig.json');
+    let mtimeMs;
+    try {
+        mtimeMs = statSync(cfgPath).mtimeMs;
+    }
+    catch {
+        return undefined;
+    }
+    const cached = tsconfigCache.get(cfgPath);
+    if (cached && cached.mtimeMs === mtimeMs)
+        return cached.paths;
+    let paths;
+    try {
+        // ts.readConfigFile parses leniently — tsconfig.json is JSONC.
+        const { config } = ts.readConfigFile(cfgPath, (p) => readFileSync(p, 'utf8'));
+        const options = config
+            ?.compilerOptions;
+        const rawPaths = options?.paths;
+        if (rawPaths && typeof rawPaths === 'object') {
+            const entries = [];
+            for (const [pattern, targetsRaw] of Object.entries(rawPaths)) {
+                if (!Array.isArray(targetsRaw))
+                    continue;
+                const targets = targetsRaw.filter((t) => typeof t === 'string');
+                const stars = pattern.split('*').length - 1;
+                if (stars === 0) {
+                    entries.push({ prefix: '', suffix: '', exact: pattern, targets });
+                }
+                else if (stars === 1) {
+                    const [prefix = '', suffix = ''] = pattern.split('*');
+                    entries.push({ prefix, suffix, targets });
+                }
+                // multi-star patterns are invalid tsconfig anyway — ignored
+            }
+            // Longest prefix wins, mirroring TS's matching order.
+            entries.sort((a, b) => (b.exact ?? b.prefix).length - (a.exact ?? a.prefix).length);
+            paths = { base: resolve(projectRoot, options?.baseUrl ?? '.'), entries };
+        }
+    }
+    catch {
+        paths = undefined;
+    }
+    tsconfigCache.set(cfgPath, { mtimeMs, paths });
+    return paths;
+}
+function resolveViaTsconfigPaths(ts, projectRoot, spec) {
+    const cfg = tsconfigPathsFor(ts, projectRoot);
+    if (!cfg)
+        return undefined;
+    for (const entry of cfg.entries) {
+        let substituted;
+        if (entry.exact !== undefined) {
+            if (spec === entry.exact)
+                substituted = entry.targets;
+        }
+        else if (spec.startsWith(entry.prefix) &&
+            spec.endsWith(entry.suffix) &&
+            spec.length >= entry.prefix.length + entry.suffix.length) {
+            const middle = spec.slice(entry.prefix.length, spec.length - entry.suffix.length);
+            substituted = entry.targets.map((t) => t.replace('*', middle));
+        }
+        if (!substituted)
+            continue;
+        for (const target of substituted) {
+            const found = resolveWithLadder(resolve(cfg.base, target));
+            if (found)
+                return found;
+        }
+    }
+    return undefined;
+}
+const NODE_BUILTINS = new Set(builtinModules);
+/** Repo-relative POSIX path when `abs` sits inside the root (and outside node_modules). */
+function projectRelative(projectRoot, abs) {
+    const rel = relative(projectRoot, abs);
+    if (rel === '' || rel.startsWith('..') || isAbsolute(rel))
+        return undefined;
+    if (rel.split('/').includes('node_modules'))
+        return undefined;
+    return rel;
+}
+/**
+ * Resolve a specifier from `importerAbs`. Project results carry the ABSOLUTE
+ * target path in `absPath` (for chain following); callers convert to
+ * repo-relative for the response.
+ */
+function resolveSpecifier(ts, projectRoot, importerAbs, spec) {
+    if (spec.startsWith('./') || spec.startsWith('../')) {
+        const target = resolveWithLadder(resolve(dirname(importerAbs), spec));
+        if (!target)
+            return { kind: 'unresolved', reason: `cannot resolve relative import '${spec}'` };
+        const rel = projectRelative(projectRoot, target);
+        if (!rel)
+            return { kind: 'unresolved', reason: 'resolves outside the project root' };
+        return { kind: 'project', path: rel, absPath: target };
+    }
+    if (isAbsolute(spec))
+        return { kind: 'unresolved', reason: 'absolute-path specifier' };
+    if (spec.startsWith('node:'))
+        return { kind: 'builtin' };
+    const viaPaths = resolveViaTsconfigPaths(ts, projectRoot, spec);
+    if (viaPaths) {
+        const rel = projectRelative(projectRoot, viaPaths);
+        if (!rel)
+            return { kind: 'unresolved', reason: 'resolves outside the project root' };
+        return { kind: 'project', path: rel, absPath: viaPaths };
+    }
+    if (NODE_BUILTINS.has(spec))
+        return { kind: 'builtin' };
+    const parts = spec.split('/');
+    const pkg = spec.startsWith('@') && parts.length >= 2 ? `${parts[0]}/${parts[1]}` : parts[0];
+    return { kind: 'external', package: pkg };
+}
+// ---------------------------------------------------------------------------
+// Re-export chain following
+const REEXPORT_DEPTH_CAP = 8;
+/**
+ * Find the file+line where `exportName` is actually DECLARED, starting at
+ * `absFile` and following named/star re-exports. Depth-capped, cycle-safe.
+ */
+function findExportedDeclaration(ts, projectRoot, absFile, exportName, depth = 0, seen = new Set()) {
+    if (depth > REEXPORT_DEPTH_CAP)
+        return undefined;
+    const key = `${absFile}::${exportName}`;
+    if (seen.has(key))
+        return undefined;
+    seen.add(key);
+    const parsed = getParsedSafe(ts, absFile);
+    if (!parsed)
+        return undefined;
+    const decl = parsed.declarations.find((d) => d.exported && d.name === exportName) ??
+        parsed.declarations.find((d) => d.name === exportName);
+    if (decl)
+        return { absFile, line: decl.line };
+    const named = parsed.reexports.find((r) => r.exported === exportName && r.source && r.source !== '*');
+    if (named) {
+        const res = resolveSpecifier(ts, projectRoot, absFile, named.from);
+        if (res.kind === 'project' && res.absPath) {
+            return findExportedDeclaration(ts, projectRoot, res.absPath, named.source, depth + 1, seen);
+        }
+        return undefined;
+    }
+    for (const star of parsed.reexports.filter((r) => r.exported === '*')) {
+        const res = resolveSpecifier(ts, projectRoot, absFile, star.from);
+        if (res.kind !== 'project' || !res.absPath)
+            continue;
+        const found = findExportedDeclaration(ts, projectRoot, res.absPath, exportName, depth + 1, seen);
+        if (found)
+            return found;
+    }
+    return undefined;
+}
+/** Resolution for an import/re-export entry, chased to the declaring file when possible. */
+function resolveEntry(ts, projectRoot, importerAbs, spec, symbolName) {
+    const res = resolveSpecifier(ts, projectRoot, importerAbs, spec);
+    if (res.kind !== 'project' || !res.absPath) {
+        const { absPath: _drop, ...pub } = res;
+        return pub;
+    }
+    if (symbolName && symbolName !== '*' && symbolName !== 'default') {
+        const found = findExportedDeclaration(ts, projectRoot, res.absPath, symbolName);
+        if (found) {
+            const rel = projectRelative(projectRoot, found.absFile);
+            if (rel)
+                return { kind: 'project', path: rel, line: found.line };
+        }
+    }
+    return { kind: 'project', path: res.path };
+}
+// ---------------------------------------------------------------------------
+// Entry point
+export async function getSourceFile(projectRoot, relPath, opts) {
+    const root = resolve(projectRoot);
+    // Generic 400: never echo the requested path back to the client.
+    if (typeof relPath !== 'string' || !isRequestPathAllowed(root, relPath)) {
+        return { ok: false, status: 400, error: 'Invalid or denied path' };
+    }
+    const abs = resolve(root, relPath);
+    let stat;
+    try {
+        stat = await fsp.stat(abs);
+    }
+    catch {
+        return { ok: false, status: 404, error: 'File not found' };
+    }
+    if (!stat.isFile())
+        return { ok: false, status: 404, error: 'File not found' };
+    const responsePath = relative(root, abs);
+    const ts = await loadTs(opts?.tsLoader);
+    if (!ts) {
+        const content = await fsp.readFile(abs, 'utf8');
+        return {
+            ok: true,
+            payload: {
+                path: responsePath,
+                content,
+                language: languageOf(abs),
+                resolver: 'unavailable',
+                symbols: { declarations: [], imports: [], reexports: [] },
+            },
+        };
+    }
+    let parsed;
+    try {
+        parsed = getParsed(ts, abs);
+    }
+    catch {
+        return { ok: false, status: 404, error: 'File not found' };
+    }
+    const imports = parsed.imports.map((raw) => ({
+        name: raw.name,
+        local: raw.local,
+        from: raw.from,
+        resolution: resolveEntry(ts, root, abs, raw.from, raw.name),
+    }));
+    for (const dyn of parsed.dynamicImports) {
+        if (dyn.from !== undefined) {
+            imports.push({
+                name: 'import()',
+                local: '',
+                from: dyn.from,
+                resolution: resolveEntry(ts, root, abs, dyn.from, undefined),
+            });
+        }
+        else {
+            imports.push({
+                name: 'import()',
+                local: '',
+                from: '(computed)',
+                resolution: { kind: 'unresolved', reason: 'dynamic import with a computed specifier' },
+            });
+        }
+    }
+    const reexports = parsed.reexports.map((raw) => ({
+        name: raw.exported,
+        from: raw.from,
+        resolution: resolveEntry(ts, root, abs, raw.from, raw.source && raw.source !== '*' ? raw.source : undefined),
+    }));
+    return {
+        ok: true,
+        payload: {
+            path: responsePath,
+            content: parsed.content,
+            language: parsed.language,
+            symbols: { declarations: parsed.declarations, imports, reexports },
+        },
+    };
+}

package/dist/src/engine/registry.d.ts

@@ -3,10 +3,30 @@ export interface RegisteredNode {
     definition: NodeDefinition;
     implementation: NodeImplementation;
 }
+/** Where a node was registered from: absolute file path + 1-based line of the register() call. */
+export interface SourceRef {
+    file: string;
+    line?: number;
+}
+export interface RegisterOptions {
+    /** Explicit provenance escape hatch — wins over automatic capture. */
+    sourceRef?: SourceRef;
+}
 export declare class NodeRegistry {
     nodes: Map<string, RegisteredNode>;
     sources: Map<string, string>;
-    register(definition: NodeDefinition, implementation: NodeImplementation): void;
+    /** Registration provenance per node type. Populated only when capture is on or opts.sourceRef given. */
+    sourceRefs: Map<string, SourceRef>;
+    /** Types the RUNNER flagged builtin (registered from the package, not the project). */
+    builtinTypes: Set<string>;
+    /** Automatic caller capture is opt-in (server registries only) so browser registries never pay/leak. */
+    private captureSourceRefs;
+    constructor(opts?: {
+        captureSourceRefs?: boolean;
+    });
+    register(definition: NodeDefinition, implementation: NodeImplementation, opts?: RegisterOptions): void;
+    /** Where `type` was registered from, when known. */
+    getSourceRef(type: string): SourceRef | undefined;
     get(type: string): RegisteredNode;
     has(type: string): boolean;
     /**
@@ -17,13 +37,18 @@ export declare class NodeRegistry {
      * process restart (which would kill in-flight agent runs).
      */
     adopt(other: NodeRegistry): void;
+    /** Whether the runner flagged `type` as a package built-in (no servable source file). */
+    isBuiltin(type: string): boolean;
     list(): NodeDefinition[];
     /**
      * Register a definition-only node (metadata fetched from the runner). Its
      * implementation is a stub that fails loudly if browser-executed — such
      * nodes run on the server. Never overwrites a real registration.
      */
-    registerDefinition(definition: NodeDefinition, source?: string): void;
+    registerDefinition(definition: NodeDefinition, source?: string, opts?: {
+        sourceRef?: SourceRef;
+        builtin?: boolean;
+    }): void;
     /** Source text for display: stored source for definition-only nodes, else the impl's toString(). */
     getSource(type: string): string | undefined;
     /**

package/dist/src/engine/registry.js

@@ -1,11 +1,78 @@
+/**
+ * Read the CALLER's file:line via a one-frame V8 stack capture.
+ * `Error.prepareStackTrace` is swapped for the duration of a single `new
+ * Error()` and restored in `finally`, so source-map hooks installed by
+ * tsx/vitest are back in place immediately. Frames arrive either as
+ * `file:///abs/path.ts` URLs (ESM) or plain absolute paths (CJS/transpilers);
+ * both normalize to a plain path. Returns undefined on any non-V8 runtime or
+ * anonymous/eval frames — capture is best-effort by design.
+ */
+function captureCallerSourceRef(skip) {
+    if (typeof Error.captureStackTrace !== 'function')
+        return undefined;
+    const original = Error.prepareStackTrace;
+    try {
+        Error.prepareStackTrace = (_err, frames) => frames;
+        const holder = {};
+        Error.captureStackTrace(holder, skip);
+        const frames = holder.stack;
+        if (!Array.isArray(frames) || frames.length === 0)
+            return undefined;
+        const frame = frames[0];
+        const raw = typeof frame.getFileName === 'function' ? frame.getFileName() : undefined;
+        if (typeof raw !== 'string' || raw.length === 0)
+            return undefined;
+        const lineRaw = typeof frame.getLineNumber === 'function' ? frame.getLineNumber() : undefined;
+        const line = typeof lineRaw === 'number' && lineRaw > 0 ? lineRaw : undefined;
+        let file = raw;
+        if (file.startsWith('file://')) {
+            // No node:url here (browser-safe module): URL parsing covers the
+            // file:///abs/path form these frames take on POSIX platforms.
+            try {
+                file = decodeURIComponent(new URL(file).pathname);
+            }
+            catch {
+                return undefined;
+            }
+        }
+        // Loaders (vite-node hot imports) may suffix ?t=... cache-busters.
+        const q = file.indexOf('?');
+        if (q !== -1)
+            file = file.slice(0, q);
+        return line !== undefined ? { file, line } : { file };
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        Error.prepareStackTrace = original;
+    }
+}
 export class NodeRegistry {
     nodes = new Map();
     sources = new Map();
-    register(definition, implementation) {
+    /** Registration provenance per node type. Populated only when capture is on or opts.sourceRef given. */
+    sourceRefs = new Map();
+    /** Types the RUNNER flagged builtin (registered from the package, not the project). */
+    builtinTypes = new Set();
+    /** Automatic caller capture is opt-in (server registries only) so browser registries never pay/leak. */
+    captureSourceRefs;
+    constructor(opts) {
+        this.captureSourceRefs = opts?.captureSourceRefs ?? false;
+    }
+    register(definition, implementation, opts) {
         if (this.nodes.has(definition.type)) {
             throw new Error(`Node type already registered: ${definition.type}`);
         }
         this.nodes.set(definition.type, { definition, implementation });
+        const ref = opts?.sourceRef ??
+            (this.captureSourceRefs ? captureCallerSourceRef(this.register) : undefined);
+        if (ref)
+            this.sourceRefs.set(definition.type, ref);
+    }
+    /** Where `type` was registered from, when known. */
+    getSourceRef(type) {
+        return this.sourceRefs.get(type);
     }
     get(type) {
         const node = this.nodes.get(type);
@@ -26,6 +93,12 @@ export class NodeRegistry {
     adopt(other) {
         this.nodes = other.nodes;
         this.sources = other.sources;
+        this.sourceRefs = other.sourceRefs;
+        this.builtinTypes = other.builtinTypes;
+    }
+    /** Whether the runner flagged `type` as a package built-in (no servable source file). */
+    isBuiltin(type) {
+        return this.builtinTypes.has(type);
     }
     list() {
         return [...this.nodes.values()].map((n) => n.definition);
@@ -35,7 +108,14 @@ export class NodeRegistry {
      * implementation is a stub that fails loudly if browser-executed — such
      * nodes run on the server. Never overwrites a real registration.
      */
-    registerDefinition(definition, source) {
+    registerDefinition(definition, source, opts) {
+        // Provenance is recorded even for already-registered types: the studio's
+        // bundled built-ins are real registrations, and the runner's builtin flag
+        // (or a project sourceRef shadowing one) must still land on them.
+        if (opts?.sourceRef)
+            this.sourceRefs.set(definition.type, opts.sourceRef);
+        if (opts?.builtin)
+            this.builtinTypes.add(definition.type);
         if (this.nodes.has(definition.type))
             return;
         this.nodes.set(definition.type, {
@@ -62,6 +142,8 @@ export class NodeRegistry {
         const next = new NodeRegistry();
         next.nodes = this.nodes;
         next.sources = this.sources;
+        next.sourceRefs = this.sourceRefs;
+        next.builtinTypes = this.builtinTypes;
         return next;
     }
 }

package/dist/src/nodes/index.d.ts

@@ -1,3 +1,9 @@
 import type { NodeRegistry } from '../engine/index.js';
-/** All built-in nodes: login examples, Open-Meteo weather, anomaly-detection API, EV charging demo, HTTP Response, requireAuth. */
-export declare function createDefaultRegistry(delayMs?: number): NodeRegistry;
+/**
+ * All built-in nodes: login examples, Open-Meteo weather, anomaly-detection API, EV charging demo, HTTP Response, requireAuth.
+ * `opts.captureSourceRefs` is threaded from SERVER callers only (buildRegistries)
+ * — this function is shared with the browser bundle, where capture stays off.
+ */
+export declare function createDefaultRegistry(delayMs?: number, opts?: {
+    captureSourceRefs?: boolean;
+}): NodeRegistry;