@deshlo/core 0.1.0

package/build/src/index.d.ts

@@ -0,0 +1,7 @@
+export { buildSourceInspectorLoaderOptions, DEFAULT_ATTRIBUTE_NAME, DEFAULT_REVISION_ATTRIBUTE_NAME, injectSourceInspectorLoader, isSourceInspectorEnabled, resolveIncludePaths, } from "./shared";
+export { injectSourceAttributes } from "./transform";
+export { buildOverlaySubmitInput, normalizeOverlayText, toOverlayErrorResult, } from "./overlay-plugin";
+export type { SourceInspectorAdapter, SourceInspectorAdapterOptions, SourceInspectorLoaderOptions, WebpackLikeConfig, } from "./shared";
+export type { InjectSourceAttributesOptions, InjectSourceAttributesResult } from "./transform";
+export type { OverlayPlugin, OverlayPluginContext, OverlayResultLink, OverlaySelection, OverlaySubmitHandler, OverlaySubmitInput, OverlaySubmitResult, TriggerKey, } from "./overlay-plugin";
+//# sourceMappingURL=index.d.ts.map

package/build/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iCAAiC,EACjC,sBAAsB,EACtB,+BAA+B,EAC/B,2BAA2B,EAC3B,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,sBAAsB,EACtB,6BAA6B,EAC7B,4BAA4B,EAC5B,iBAAiB,GAClB,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,6BAA6B,EAAE,4BAA4B,EAAE,MAAM,aAAa,CAAC;AAC/F,YAAY,EACV,aAAa,EACb,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACnB,UAAU,GACX,MAAM,kBAAkB,CAAC"}

package/build/src/index.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toOverlayErrorResult = exports.normalizeOverlayText = exports.buildOverlaySubmitInput = exports.injectSourceAttributes = exports.resolveIncludePaths = exports.isSourceInspectorEnabled = exports.injectSourceInspectorLoader = exports.DEFAULT_REVISION_ATTRIBUTE_NAME = exports.DEFAULT_ATTRIBUTE_NAME = exports.buildSourceInspectorLoaderOptions = void 0;
+var shared_1 = require("./shared");
+Object.defineProperty(exports, "buildSourceInspectorLoaderOptions", { enumerable: true, get: function () { return shared_1.buildSourceInspectorLoaderOptions; } });
+Object.defineProperty(exports, "DEFAULT_ATTRIBUTE_NAME", { enumerable: true, get: function () { return shared_1.DEFAULT_ATTRIBUTE_NAME; } });
+Object.defineProperty(exports, "DEFAULT_REVISION_ATTRIBUTE_NAME", { enumerable: true, get: function () { return shared_1.DEFAULT_REVISION_ATTRIBUTE_NAME; } });
+Object.defineProperty(exports, "injectSourceInspectorLoader", { enumerable: true, get: function () { return shared_1.injectSourceInspectorLoader; } });
+Object.defineProperty(exports, "isSourceInspectorEnabled", { enumerable: true, get: function () { return shared_1.isSourceInspectorEnabled; } });
+Object.defineProperty(exports, "resolveIncludePaths", { enumerable: true, get: function () { return shared_1.resolveIncludePaths; } });
+var transform_1 = require("./transform");
+Object.defineProperty(exports, "injectSourceAttributes", { enumerable: true, get: function () { return transform_1.injectSourceAttributes; } });
+var overlay_plugin_1 = require("./overlay-plugin");
+Object.defineProperty(exports, "buildOverlaySubmitInput", { enumerable: true, get: function () { return overlay_plugin_1.buildOverlaySubmitInput; } });
+Object.defineProperty(exports, "normalizeOverlayText", { enumerable: true, get: function () { return overlay_plugin_1.normalizeOverlayText; } });
+Object.defineProperty(exports, "toOverlayErrorResult", { enumerable: true, get: function () { return overlay_plugin_1.toOverlayErrorResult; } });

package/build/src/overlay-plugin.d.ts

@@ -0,0 +1,31 @@
+export type TriggerKey = "alt" | "shift" | "meta" | "ctrl";
+export interface OverlaySelection {
+    sourceLoc: string;
+    tagName: string;
+    selectedText: string;
+    commitSha?: string;
+}
+export interface OverlaySubmitInput extends OverlaySelection {
+    proposedText: string;
+}
+export interface OverlayResultLink {
+    label: string;
+    url: string;
+}
+export interface OverlaySubmitResult {
+    ok: boolean;
+    message: string;
+    links?: OverlayResultLink[];
+}
+export interface OverlayPluginContext {
+    host: string;
+}
+export type OverlaySubmitHandler = (input: OverlaySubmitInput, context: OverlayPluginContext) => Promise<OverlaySubmitResult> | OverlaySubmitResult;
+export interface OverlayPlugin {
+    id: string;
+    submit: OverlaySubmitHandler;
+}
+export declare function normalizeOverlayText(value: string): string;
+export declare function buildOverlaySubmitInput(selection: OverlaySelection, proposedText: string): OverlaySubmitInput;
+export declare function toOverlayErrorResult(error: unknown): OverlaySubmitResult;
+//# sourceMappingURL=overlay-plugin.d.ts.map

package/build/src/overlay-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay-plugin.d.ts","sourceRoot":"","sources":["../../src/overlay-plugin.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAE3D,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,kBAAmB,SAAQ,gBAAgB;IAC1D,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,iBAAiB,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,oBAAoB,GAAG,CACjC,KAAK,EAAE,kBAAkB,EACzB,OAAO,EAAE,oBAAoB,KAC1B,OAAO,CAAC,mBAAmB,CAAC,GAAG,mBAAmB,CAAC;AAExD,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,oBAAoB,CAAC;CAC9B;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,gBAAgB,EAC3B,YAAY,EAAE,MAAM,GACnB,kBAAkB,CAQpB;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CAYxE"}

package/build/src/overlay-plugin.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeOverlayText = normalizeOverlayText;
+exports.buildOverlaySubmitInput = buildOverlaySubmitInput;
+exports.toOverlayErrorResult = toOverlayErrorResult;
+function normalizeOverlayText(value) {
+    return value.replace(/\s+/g, " ").trim();
+}
+function buildOverlaySubmitInput(selection, proposedText) {
+    return {
+        sourceLoc: selection.sourceLoc,
+        tagName: selection.tagName,
+        selectedText: selection.selectedText,
+        commitSha: selection.commitSha ?? "unknown",
+        proposedText: proposedText.trim(),
+    };
+}
+function toOverlayErrorResult(error) {
+    if (error instanceof Error) {
+        return {
+            ok: false,
+            message: error.message,
+        };
+    }
+    return {
+        ok: false,
+        message: "Unexpected plugin error.",
+    };
+}

package/build/src/revision.d.ts

@@ -0,0 +1,2 @@
+export declare function resolveBuildCommitSha(): string;
+//# sourceMappingURL=revision.d.ts.map

package/build/src/revision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"revision.d.ts","sourceRoot":"","sources":["../../src/revision.ts"],"names":[],"mappings":"AAqCA,wBAAgB,qBAAqB,IAAI,MAAM,CAY9C"}

package/build/src/revision.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveBuildCommitSha = resolveBuildCommitSha;
+const node_child_process_1 = require("node:child_process");
+const COMMIT_ENV_KEYS = [
+    "COMMIT_SHA",
+    "SOURCE_VERSION",
+    "GITHUB_SHA",
+    "CI_COMMIT_SHA",
+    "GIT_COMMIT",
+    "VERCEL_GIT_COMMIT_SHA",
+    "RENDER_GIT_COMMIT",
+];
+let cachedCommitSha = null;
+function resolveCommitFromEnv() {
+    for (const key of COMMIT_ENV_KEYS) {
+        const value = process.env[key]?.trim();
+        if (value) {
+            return value;
+        }
+    }
+    return null;
+}
+function resolveCommitFromGit() {
+    try {
+        const value = (0, node_child_process_1.execSync)("git rev-parse HEAD", {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        return value.length > 0 ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+function resolveBuildCommitSha() {
+    if (cachedCommitSha) {
+        return cachedCommitSha;
+    }
+    const resolved = resolveCommitFromEnv() ??
+        resolveCommitFromGit() ??
+        "unknown";
+    cachedCommitSha = resolved;
+    return resolved;
+}

package/build/src/shared.d.ts

@@ -0,0 +1,30 @@
+export interface SourceInspectorAdapterOptions {
+    enabled?: boolean;
+    include?: string[];
+    attributeName?: string;
+    wrapLooseTextNodes?: boolean;
+    annotateLeafNodesOnly?: boolean;
+}
+export interface SourceInspectorLoaderOptions {
+    attributeName: string;
+    wrapLooseTextNodes: boolean;
+    annotateLeafNodesOnly: boolean;
+    includePaths: string[];
+}
+export interface WebpackLikeConfig {
+    module?: {
+        rules?: unknown[];
+    };
+    [key: string]: unknown;
+}
+export interface SourceInspectorAdapter<TConfig = unknown> {
+    id: string;
+    apply: (config: TConfig, options?: SourceInspectorAdapterOptions) => TConfig;
+}
+export declare const DEFAULT_ATTRIBUTE_NAME = "data-src-loc";
+export declare const DEFAULT_REVISION_ATTRIBUTE_NAME = "data-src-rev";
+export declare function buildSourceInspectorLoaderOptions(options?: SourceInspectorAdapterOptions, cwd?: string): SourceInspectorLoaderOptions;
+export declare function isSourceInspectorEnabled(options: SourceInspectorAdapterOptions): boolean;
+export declare function resolveIncludePaths(include: string[] | undefined, cwd?: string): string[];
+export declare function injectSourceInspectorLoader<TConfig extends WebpackLikeConfig>(webpackConfig: TConfig, options?: SourceInspectorAdapterOptions, cwd?: string): TConfig;
+//# sourceMappingURL=shared.d.ts.map

package/build/src/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/shared.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,6BAA6B;IAC5C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAED,MAAM,WAAW,4BAA4B;IAC3C,aAAa,EAAE,MAAM,CAAC;IACtB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,qBAAqB,EAAE,OAAO,CAAC;IAC/B,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE;QACP,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;KACnB,CAAC;IACF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,sBAAsB,CAAC,OAAO,GAAG,OAAO;IACvD,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,6BAA6B,KAAK,OAAO,CAAC;CAC9E;AAED,eAAO,MAAM,sBAAsB,iBAAiB,CAAC;AACrD,eAAO,MAAM,+BAA+B,iBAAiB,CAAC;AAE9D,wBAAgB,iCAAiC,CAC/C,OAAO,GAAE,6BAAkC,EAC3C,GAAG,GAAE,MAAsB,GAC1B,4BAA4B,CAO9B;AAED,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,6BAA6B,GAAG,OAAO,CAUxF;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EAAE,GAAG,SAAS,EAC7B,GAAG,GAAE,MAAsB,GAC1B,MAAM,EAAE,CAGV;AAED,wBAAgB,2BAA2B,CAAC,OAAO,SAAS,iBAAiB,EAC3E,aAAa,EAAE,OAAO,EACtB,OAAO,GAAE,6BAAkC,EAC3C,GAAG,GAAE,MAAsB,GAC1B,OAAO,CAoBT"}

package/build/src/shared.js

@@ -0,0 +1,52 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_REVISION_ATTRIBUTE_NAME = exports.DEFAULT_ATTRIBUTE_NAME = void 0;
+exports.buildSourceInspectorLoaderOptions = buildSourceInspectorLoaderOptions;
+exports.isSourceInspectorEnabled = isSourceInspectorEnabled;
+exports.resolveIncludePaths = resolveIncludePaths;
+exports.injectSourceInspectorLoader = injectSourceInspectorLoader;
+const node_path_1 = __importDefault(require("node:path"));
+exports.DEFAULT_ATTRIBUTE_NAME = "data-src-loc";
+exports.DEFAULT_REVISION_ATTRIBUTE_NAME = "data-src-rev";
+function buildSourceInspectorLoaderOptions(options = {}, cwd = process.cwd()) {
+    return {
+        attributeName: options.attributeName ?? exports.DEFAULT_ATTRIBUTE_NAME,
+        wrapLooseTextNodes: options.wrapLooseTextNodes === true,
+        annotateLeafNodesOnly: options.annotateLeafNodesOnly === true,
+        includePaths: resolveIncludePaths(options.include, cwd),
+    };
+}
+function isSourceInspectorEnabled(options) {
+    if (typeof options.enabled === "boolean") {
+        return options.enabled;
+    }
+    return (process.env.NEXT_PUBLIC_SOURCE_INSPECTOR === "1" ||
+        process.env.VITE_SOURCE_INSPECTOR === "1" ||
+        process.env.SOURCE_INSPECTOR === "1");
+}
+function resolveIncludePaths(include, cwd = process.cwd()) {
+    const entries = include && include.length > 0 ? include : [node_path_1.default.resolve(cwd, "src")];
+    return entries.map((entry) => node_path_1.default.resolve(cwd, entry));
+}
+function injectSourceInspectorLoader(webpackConfig, options = {}, cwd = process.cwd()) {
+    var _a;
+    const loaderOptions = buildSourceInspectorLoaderOptions(options, cwd);
+    webpackConfig.module ?? (webpackConfig.module = {});
+    (_a = webpackConfig.module).rules ?? (_a.rules = []);
+    webpackConfig.module.rules.unshift({
+        test: /\.[jt]sx?$/,
+        include: loaderOptions.includePaths,
+        exclude: /node_modules/,
+        enforce: "pre",
+        use: [
+            {
+                loader: "@deshlo/loader",
+                options: loaderOptions,
+            },
+        ],
+    });
+    return webpackConfig;
+}

package/build/src/transform.d.ts

@@ -0,0 +1,13 @@
+export interface InjectSourceAttributesOptions {
+    attributeName?: string;
+    cwd?: string;
+    wrapLooseTextNodes?: boolean;
+    annotateLeafNodesOnly?: boolean;
+}
+export interface InjectSourceAttributesResult {
+    code: string;
+    map: unknown;
+    changed: boolean;
+}
+export declare function injectSourceAttributes(source: string, resourcePath: string, options?: InjectSourceAttributesOptions): InjectSourceAttributesResult;
+//# sourceMappingURL=transform.d.ts.map

package/build/src/transform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform.d.ts","sourceRoot":"","sources":["../../src/transform.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,6BAA6B;IAC5C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAED,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,OAAO,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;CAClB;AAwED,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,6BAAkC,GAC1C,4BAA4B,CA6L9B"}

package/build/src/transform.js

@@ -0,0 +1,227 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.injectSourceAttributes = injectSourceAttributes;
+const node_path_1 = __importDefault(require("node:path"));
+const parser = __importStar(require("@babel/parser"));
+const generator_1 = __importDefault(require("@babel/generator"));
+const traverse_1 = __importDefault(require("@babel/traverse"));
+const t = __importStar(require("@babel/types"));
+const revision_1 = require("./revision");
+const shared_1 = require("./shared");
+function toRelativePath(absolutePath, cwd) {
+    return node_path_1.default.relative(cwd, absolutePath).replace(/\\/g, "/");
+}
+function splitMeaningfulText(value) {
+    let firstNonWhitespace = -1;
+    for (let index = 0; index < value.length; index += 1) {
+        if (value[index].trim() !== "") {
+            firstNonWhitespace = index;
+            break;
+        }
+    }
+    if (firstNonWhitespace === -1) {
+        return null;
+    }
+    let lastNonWhitespace = -1;
+    for (let index = value.length - 1; index >= 0; index -= 1) {
+        if (value[index].trim() !== "") {
+            lastNonWhitespace = index;
+            break;
+        }
+    }
+    if (lastNonWhitespace === -1) {
+        return null;
+    }
+    return {
+        leading: value.slice(0, firstNonWhitespace),
+        text: value.slice(firstNonWhitespace, lastNonWhitespace + 1),
+        trailing: value.slice(lastNonWhitespace + 1),
+    };
+}
+function advanceLocation(start, value) {
+    let line = start.line;
+    let column = start.column;
+    for (const character of value) {
+        if (character === "\n") {
+            line += 1;
+            column = 0;
+            continue;
+        }
+        if (character === "\r") {
+            continue;
+        }
+        column += 1;
+    }
+    return { line, column };
+}
+function isHostElement(nameNode) {
+    return t.isJSXIdentifier(nameNode) && /^[a-z]/.test(nameNode.name);
+}
+function hasJsxElementChildren(node) {
+    return node.children.some((child) => t.isJSXElement(child) || t.isJSXFragment(child));
+}
+function injectSourceAttributes(source, resourcePath, options = {}) {
+    const attributeName = typeof options.attributeName === "string" && options.attributeName.trim().length > 0
+        ? options.attributeName.trim()
+        : shared_1.DEFAULT_ATTRIBUTE_NAME;
+    const revisionValue = (0, revision_1.resolveBuildCommitSha)();
+    if (typeof source !== "string" || !source.includes("<")) {
+        return { code: source, map: null, changed: false };
+    }
+    const cwd = options.cwd ?? process.cwd();
+    const relativePath = toRelativePath(resourcePath, cwd);
+    const wrapLooseTextNodes = options.wrapLooseTextNodes === true;
+    const annotateLeafNodesOnly = options.annotateLeafNodesOnly === true;
+    let ast;
+    try {
+        ast = parser.parse(source, {
+            sourceType: "unambiguous",
+            errorRecovery: true,
+            plugins: [
+                "jsx",
+                "typescript",
+                "classProperties",
+                "classPrivateProperties",
+                "classPrivateMethods",
+                "dynamicImport",
+                "importMeta",
+                "topLevelAwait",
+            ],
+        });
+    }
+    catch {
+        return { code: source, map: null, changed: false };
+    }
+    let changed = false;
+    (0, traverse_1.default)(ast, {
+        JSXOpeningElement(openingPath) {
+            const nameNode = openingPath.node.name;
+            if (!isHostElement(nameNode)) {
+                return;
+            }
+            if (!openingPath.node.loc) {
+                return;
+            }
+            if (annotateLeafNodesOnly) {
+                const parentNode = openingPath.parentPath.node;
+                if (t.isJSXElement(parentNode) && hasJsxElementChildren(parentNode)) {
+                    return;
+                }
+            }
+            const hasSourceAttribute = openingPath.node.attributes.some((attribute) => t.isJSXAttribute(attribute) &&
+                t.isJSXIdentifier(attribute.name, { name: attributeName }));
+            const hasRevisionAttribute = openingPath.node.attributes.some((attribute) => t.isJSXAttribute(attribute) &&
+                t.isJSXIdentifier(attribute.name, { name: shared_1.DEFAULT_REVISION_ATTRIBUTE_NAME }));
+            if (hasSourceAttribute && hasRevisionAttribute) {
+                return;
+            }
+            const { line, column } = openingPath.node.loc.start;
+            const locationValue = `${relativePath}:${line}:${column + 1}`;
+            if (!hasSourceAttribute) {
+                openingPath.node.attributes.push(t.jsxAttribute(t.jsxIdentifier(attributeName), t.stringLiteral(locationValue)));
+                changed = true;
+            }
+            if (!hasRevisionAttribute) {
+                openingPath.node.attributes.push(t.jsxAttribute(t.jsxIdentifier(shared_1.DEFAULT_REVISION_ATTRIBUTE_NAME), t.stringLiteral(revisionValue)));
+                changed = true;
+            }
+        },
+        JSXElement(elementPath) {
+            if (!wrapLooseTextNodes) {
+                return;
+            }
+            const nameNode = elementPath.node.openingElement.name;
+            if (!isHostElement(nameNode)) {
+                return;
+            }
+            const children = elementPath.node.children;
+            if (children.length === 0) {
+                return;
+            }
+            // Only wrap loose text when mixed with other child nodes.
+            const hasNonTextSiblings = children.some((child) => t.isJSXElement(child) || t.isJSXFragment(child) || t.isJSXExpressionContainer(child));
+            if (!hasNonTextSiblings) {
+                return;
+            }
+            const nextChildren = [];
+            let wrappedAnyTextNode = false;
+            for (const child of children) {
+                if (!t.isJSXText(child) || !child.loc) {
+                    nextChildren.push(child);
+                    continue;
+                }
+                const parts = splitMeaningfulText(child.value);
+                if (!parts) {
+                    nextChildren.push(child);
+                    continue;
+                }
+                const textStart = advanceLocation({ line: child.loc.start.line, column: child.loc.start.column }, parts.leading);
+                const locationValue = `${relativePath}:${textStart.line}:${textStart.column + 1}`;
+                if (parts.leading.length > 0) {
+                    nextChildren.push(t.jsxText(parts.leading));
+                }
+                nextChildren.push(t.jsxElement(t.jsxOpeningElement(t.jsxIdentifier("span"), [
+                    t.jsxAttribute(t.jsxIdentifier(attributeName), t.stringLiteral(locationValue)),
+                    t.jsxAttribute(t.jsxIdentifier(shared_1.DEFAULT_REVISION_ATTRIBUTE_NAME), t.stringLiteral(revisionValue)),
+                ]), t.jsxClosingElement(t.jsxIdentifier("span")), [t.jsxText(parts.text)], false));
+                if (parts.trailing.length > 0) {
+                    nextChildren.push(t.jsxText(parts.trailing));
+                }
+                wrappedAnyTextNode = true;
+                changed = true;
+            }
+            if (wrappedAnyTextNode) {
+                elementPath.node.children = nextChildren;
+            }
+        },
+    });
+    if (!changed) {
+        return { code: source, map: null, changed: false };
+    }
+    const output = (0, generator_1.default)(ast, {
+        sourceMaps: true,
+        sourceFileName: relativePath,
+        jsescOption: { minimal: true },
+    }, source);
+    return {
+        code: output.code,
+        map: output.map,
+        changed: true,
+    };
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@deshlo/core",
+  "version": "0.1.0",
+  "description": "Shared source inspector helper/wrapper utilities and contracts",
+  "main": "build/src/index.js",
+  "module": "build/src/index.js",
+  "types": "build/src/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./build/src/index.d.ts",
+      "require": "./build/src/index.js",
+      "import": "./build/src/index.js"
+    },
+    "./overlay-plugin": {
+      "types": "./build/src/overlay-plugin.d.ts",
+      "require": "./build/src/overlay-plugin.js",
+      "import": "./build/src/overlay-plugin.js"
+    }
+  },
+  "files": [
+    "build"
+  ],
+  "scripts": {
+    "clean": "rm -rf build",
+    "build": "tsc -p tsconfig.json",
+    "test": "echo \"No tests yet\""
+  },
+  "keywords": [
+    "source-map",
+    "debug",
+    "inspector"
+  ],
+  "author": "Nikos Gerontakis",
+  "license": "MIT",
+  "dependencies": {
+    "@babel/generator": "^7.28.3",
+    "@babel/parser": "^7.28.4",
+    "@babel/traverse": "^7.29.0",
+    "@babel/types": "^7.28.4",
+    "@deshlo/loader": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1"
+  }
+}