feega-source-map 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,23 @@
1
- # Temporary Holding Version
1
+ # feega-source-map
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Dev-only plugins that tag every element with the `file:line:col` that wrote it, so [Feega](https://feega.app) can open, and edit, the source behind what you click in a live frame.
4
+
5
+ ```bash
6
+ npx feega init # adds the plugin to vite.config or next.config
7
+ ```
8
+
9
+ Or by hand:
10
+
11
+ ```ts
12
+ // vite.config.ts (React, Svelte, SvelteKit)
13
+ import { feegaSource } from 'feega-source-map/vite';
14
+ export default defineConfig({ plugins: [feegaSource(), /* ... */] });
15
+ ```
16
+
17
+ ```js
18
+ // next.config.mjs (webpack dev server)
19
+ import { withFeegaSource } from 'feega-source-map/next';
20
+ export default withFeegaSource({ /* your config */ });
21
+ ```
22
+
23
+ Nothing is added to production builds. Docs: https://docs.feega.app/integrations/source-map/
@@ -0,0 +1,5 @@
1
+ export function installBridge(win: any): void;
2
+ export const INSPECT: "feega:inspect";
3
+ export const INSPECT_RESULT: "feega:inspect:result";
4
+ export const READY: "feega:source-map:ready";
5
+ export const PREVIEW: "feega:preview";
package/dist/bridge.js ADDED
@@ -0,0 +1,35 @@
1
+ import { inspectElement, previewEdit } from './runtime.js';
2
+ export const INSPECT = 'feega:inspect';
3
+ export const INSPECT_RESULT = 'feega:inspect:result';
4
+ export const READY = 'feega:source-map:ready';
5
+ export const PREVIEW = 'feega:preview';
6
+ const INSTALLED = Symbol.for('feega.source-map.bridge');
7
+ export function installBridge(win) {
8
+ if (win[INSTALLED]) {
9
+ return;
10
+ }
11
+ win[INSTALLED] = true;
12
+ win.addEventListener('message', (event) => {
13
+ const request = event.data;
14
+ if (request?.type === PREVIEW) {
15
+ previewEdit(win.document, request);
16
+ return;
17
+ }
18
+ if (!request || request.type !== INSPECT) {
19
+ return;
20
+ }
21
+ const target = targetOf(win.document, request);
22
+ const result = target ? inspectElement(target, { maxHtml: request.maxHtml }) : null;
23
+ event.source?.postMessage({ type: INSPECT_RESULT, id: request.id, result }, { targetOrigin: '*' });
24
+ });
25
+ win.parent?.postMessage({ type: READY }, '*');
26
+ }
27
+ function targetOf(doc, request) {
28
+ if (typeof request.selector === 'string') {
29
+ return doc.querySelector(request.selector);
30
+ }
31
+ return doc.elementFromPoint(request.x, request.y);
32
+ }
33
+ if (typeof window !== 'undefined') {
34
+ installBridge(window);
35
+ }
@@ -0,0 +1,3 @@
1
+ export declare const SOURCE_ATTR = "data-feega-src";
2
+ export declare const MAPPED_EXTENSIONS: string[];
3
+ export declare function injectSource(code: string, file: string): string | null;
package/dist/inject.js ADDED
@@ -0,0 +1,97 @@
1
+ import { createRequire } from 'node:module';
2
+ import { parse as parseJs } from '@babel/parser';
3
+ import MagicString from 'magic-string';
4
+ export const SOURCE_ATTR = 'data-feega-src';
5
+ const require = createRequire(import.meta.url);
6
+ const HOST_TAG = /^[a-z][\w-]*$/;
7
+ const FINDERS = {
8
+ '.jsx': (code) => jsxTags(code, ['jsx']),
9
+ '.tsx': (code) => jsxTags(code, ['jsx', 'typescript']),
10
+ '.svelte': svelteTags
11
+ };
12
+ export const MAPPED_EXTENSIONS = Object.keys(FINDERS);
13
+ export function injectSource(code, file) {
14
+ const finder = FINDERS[extensionOf(file)];
15
+ if (!finder || code.includes(SOURCE_ATTR)) {
16
+ return null;
17
+ }
18
+ const tags = finder(code);
19
+ if (tags.length === 0) {
20
+ return null;
21
+ }
22
+ const out = new MagicString(code);
23
+ for (const tag of tags) {
24
+ out.appendLeft(tag.nameEnd, ` ${SOURCE_ATTR}="${file}:${tag.line}:${tag.col}"`);
25
+ }
26
+ return out.toString();
27
+ }
28
+ function extensionOf(file) {
29
+ const clean = file.split('?')[0];
30
+ return clean.slice(clean.lastIndexOf('.'));
31
+ }
32
+ function jsxTags(code, plugins) {
33
+ const ast = parseJs(code, { sourceType: 'module', plugins, errorRecovery: true });
34
+ const tags = [];
35
+ walk(ast.program, (node) => {
36
+ if (node.type !== 'JSXOpeningElement') {
37
+ return;
38
+ }
39
+ const name = node.name;
40
+ if (name.type !== 'JSXIdentifier' || !HOST_TAG.test(name.name ?? '')) {
41
+ return;
42
+ }
43
+ const start = node.loc.start;
44
+ tags.push({ nameEnd: name.end, line: start.line, col: start.column + 1 });
45
+ });
46
+ return tags;
47
+ }
48
+ function svelteTags(code) {
49
+ const { parse } = require('svelte/compiler');
50
+ const ast = parse(code, { modern: true });
51
+ const lineStarts = lineStartsOf(code);
52
+ const tags = [];
53
+ walk(ast.fragment, (node) => {
54
+ if (node.type !== 'RegularElement') {
55
+ return;
56
+ }
57
+ const start = node.start;
58
+ const nameEnd = start + 1 + node.name.length;
59
+ tags.push({ nameEnd, ...position(lineStarts, start) });
60
+ });
61
+ return tags;
62
+ }
63
+ function lineStartsOf(code) {
64
+ const starts = [0];
65
+ for (let i = 0; i < code.length; i++) {
66
+ if (code[i] === '\n') {
67
+ starts.push(i + 1);
68
+ }
69
+ }
70
+ return starts;
71
+ }
72
+ function position(lineStarts, offset) {
73
+ let line = 0;
74
+ while (line + 1 < lineStarts.length && lineStarts[line + 1] <= offset) {
75
+ line++;
76
+ }
77
+ return { line: line + 1, col: offset - lineStarts[line] + 1 };
78
+ }
79
+ function walk(node, visit) {
80
+ if (Array.isArray(node)) {
81
+ node.forEach((child) => walk(child, visit));
82
+ return;
83
+ }
84
+ if (!node || typeof node !== 'object') {
85
+ return;
86
+ }
87
+ const record = node;
88
+ if (typeof record.type === 'string') {
89
+ visit(record);
90
+ }
91
+ for (const [key, value] of Object.entries(record)) {
92
+ if (key === 'loc' || key === 'parent') {
93
+ continue;
94
+ }
95
+ walk(value, visit);
96
+ }
97
+ }
@@ -0,0 +1,8 @@
1
+ type LoaderContext = {
2
+ resourcePath: string;
3
+ getOptions(): {
4
+ root: string;
5
+ };
6
+ };
7
+ export default function feegaSourceLoader(this: LoaderContext, source: string): string;
8
+ export {};
@@ -0,0 +1,6 @@
1
+ import { relative } from 'node:path';
2
+ import { injectSource } from "./inject.js";
3
+ export default function feegaSourceLoader(source) {
4
+ const { root } = this.getOptions();
5
+ return injectSource(source, relative(root, this.resourcePath)) ?? source;
6
+ }
package/dist/next.d.ts ADDED
@@ -0,0 +1,21 @@
1
+ type EntryValue = string | string[] | {
2
+ import: string[];
3
+ };
4
+ type Entries = Record<string, EntryValue>;
5
+ type WebpackConfig = {
6
+ entry: () => Promise<Entries>;
7
+ module: {
8
+ rules: unknown[];
9
+ };
10
+ };
11
+ type WebpackContext = {
12
+ dev: boolean;
13
+ isServer: boolean;
14
+ dir: string;
15
+ };
16
+ type NextConfig = {
17
+ webpack?: (config: WebpackConfig, context: WebpackContext) => WebpackConfig;
18
+ [key: string]: unknown;
19
+ };
20
+ export declare function withFeegaSource<T extends NextConfig>(nextConfig?: T): T;
21
+ export {};
package/dist/next.js ADDED
@@ -0,0 +1,47 @@
1
+ import { extname } from 'node:path';
2
+ import { fileURLToPath } from 'node:url';
3
+ const OWN_EXTENSION = extname(fileURLToPath(import.meta.url));
4
+ const LOADER_PATH = fileURLToPath(new URL(`./next-loader${OWN_EXTENSION}`, import.meta.url));
5
+ const BRIDGE_PATH = fileURLToPath(new URL('./bridge.js', import.meta.url));
6
+ const CLIENT_ENTRIES = ['main-app', 'main'];
7
+ export function withFeegaSource(nextConfig = {}) {
8
+ return {
9
+ ...nextConfig,
10
+ webpack(config, context) {
11
+ const out = nextConfig.webpack ? nextConfig.webpack(config, context) : config;
12
+ if (!context.dev) {
13
+ return out;
14
+ }
15
+ out.module.rules.push({
16
+ test: /\.(jsx|tsx)$/,
17
+ exclude: /node_modules/,
18
+ enforce: 'pre',
19
+ use: [{ loader: LOADER_PATH, options: { root: context.dir } }]
20
+ });
21
+ if (!context.isServer) {
22
+ out.entry = withBridge(out.entry);
23
+ }
24
+ return out;
25
+ }
26
+ };
27
+ }
28
+ function withBridge(entry) {
29
+ return async () => {
30
+ const entries = await entry();
31
+ for (const name of CLIENT_ENTRIES) {
32
+ if (entries[name]) {
33
+ entries[name] = prepend(entries[name]);
34
+ }
35
+ }
36
+ return entries;
37
+ };
38
+ }
39
+ function prepend(value) {
40
+ if (typeof value === 'string') {
41
+ return [BRIDGE_PATH, value];
42
+ }
43
+ if (Array.isArray(value)) {
44
+ return value.includes(BRIDGE_PATH) ? value : [BRIDGE_PATH, ...value];
45
+ }
46
+ return { ...value, import: prepend(value.import) };
47
+ }
@@ -0,0 +1,39 @@
1
+ export function parseSource(value: any): {
2
+ file: string;
3
+ line: number;
4
+ col: number;
5
+ } | null;
6
+ export function inspectElement(element: any, { maxHtml }?: {
7
+ maxHtml?: number | undefined;
8
+ }): {
9
+ source: {
10
+ file: string;
11
+ line: number;
12
+ col: number;
13
+ } | null;
14
+ styles: {
15
+ [k: string]: any;
16
+ };
17
+ html: any;
18
+ component: {
19
+ file: string;
20
+ line: number;
21
+ col: number;
22
+ } | null;
23
+ rect: {
24
+ x: any;
25
+ y: any;
26
+ width: any;
27
+ height: any;
28
+ };
29
+ classes: any;
30
+ text: any;
31
+ rem: number;
32
+ viewport: any;
33
+ } | null;
34
+ export function previewEdit(doc: any, { source, text, style }: {
35
+ source: any;
36
+ text: any;
37
+ style: any;
38
+ }): void;
39
+ export const SOURCE_ATTR: "data-feega-src";
@@ -0,0 +1,69 @@
1
+ export const SOURCE_ATTR = 'data-feega-src';
2
+ const DEFAULT_MAX_HTML = 2000;
3
+ const DESIGN_PROPERTIES = [
4
+ 'display', 'position', 'width', 'height',
5
+ 'margin-top', 'margin-right', 'margin-bottom', 'margin-left',
6
+ 'padding-top', 'padding-right', 'padding-bottom', 'padding-left',
7
+ 'gap', 'flex-direction', 'justify-content', 'align-items', 'grid-template-columns',
8
+ 'color', 'background-color', 'background-image', 'opacity',
9
+ 'border-top-width', 'border-top-style', 'border-top-color', 'border-radius', 'box-shadow',
10
+ 'font-family', 'font-size', 'font-weight', 'line-height', 'letter-spacing', 'text-align', 'text-transform'
11
+ ];
12
+ const SOURCE_PATTERN = /^(.+):(\d+):(\d+)$/;
13
+ export function parseSource(value) {
14
+ const match = SOURCE_PATTERN.exec(value ?? '');
15
+ if (!match) {
16
+ return null;
17
+ }
18
+ return { file: match[1], line: Number(match[2]), col: Number(match[3]) };
19
+ }
20
+ export function inspectElement(element, { maxHtml = DEFAULT_MAX_HTML } = {}) {
21
+ const tagged = element.closest(`[${SOURCE_ATTR}]`);
22
+ if (!tagged) {
23
+ return null;
24
+ }
25
+ const source = parseSource(tagged.getAttribute(SOURCE_ATTR));
26
+ return {
27
+ source,
28
+ styles: designStyles(tagged),
29
+ html: truncate(tagged.outerHTML, maxHtml),
30
+ component: componentBoundary(tagged, source.file),
31
+ rect: rectOf(tagged),
32
+ classes: tagged.getAttribute('class') ?? '',
33
+ text: tagged.children.length ? null : tagged.textContent,
34
+ rem: rootFontSize(tagged.ownerDocument),
35
+ viewport: tagged.ownerDocument.defaultView.innerWidth
36
+ };
37
+ }
38
+ function rootFontSize(doc) {
39
+ return parseFloat(doc.defaultView.getComputedStyle(doc.documentElement).fontSize);
40
+ }
41
+ function rectOf(element) {
42
+ const { x, y, width, height } = element.getBoundingClientRect();
43
+ return { x, y, width, height };
44
+ }
45
+ export function previewEdit(doc, { source, text, style }) {
46
+ const sourced = [...doc.querySelectorAll(`[${SOURCE_ATTR}]`)].filter((e) => e.getAttribute(SOURCE_ATTR) === source);
47
+ for (const element of sourced) {
48
+ if (typeof text === 'string') {
49
+ element.textContent = text;
50
+ }
51
+ Object.entries(style ?? {}).forEach(([name, value]) => element.style.setProperty(name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`), value));
52
+ }
53
+ }
54
+ function designStyles(element) {
55
+ const computed = element.ownerDocument.defaultView.getComputedStyle(element);
56
+ return Object.fromEntries(DESIGN_PROPERTIES.map((name) => [name, computed.getPropertyValue(name)]));
57
+ }
58
+ function truncate(text, max) {
59
+ return text.length <= max ? text : `${text.slice(0, max)}…`;
60
+ }
61
+ function componentBoundary(element, file) {
62
+ for (let node = element.parentElement?.closest(`[${SOURCE_ATTR}]`); node; node = node.parentElement?.closest(`[${SOURCE_ATTR}]`)) {
63
+ const source = parseSource(node.getAttribute(SOURCE_ATTR));
64
+ if (source && source.file !== file) {
65
+ return source;
66
+ }
67
+ }
68
+ return null;
69
+ }
package/dist/vite.d.ts ADDED
@@ -0,0 +1,2 @@
1
+ import { type Plugin } from 'vite';
2
+ export declare function feegaSource(): Plugin;
package/dist/vite.js ADDED
@@ -0,0 +1,31 @@
1
+ import { fileURLToPath } from 'node:url';
2
+ import { dirname, relative } from 'node:path';
3
+ import { searchForWorkspaceRoot } from 'vite';
4
+ import { injectSource } from "./inject.js";
5
+ const BRIDGE_PATH = fileURLToPath(new URL('./bridge.js', import.meta.url));
6
+ const VITE_CLIENT = /\/vite\/dist\/client\/client\.mjs$/;
7
+ const BRIDGE_IMPORT = `import ${JSON.stringify(`/@fs${BRIDGE_PATH}`)};`;
8
+ export function feegaSource() {
9
+ let root = process.cwd();
10
+ return {
11
+ name: 'feega-source-map',
12
+ apply: 'serve',
13
+ enforce: 'pre',
14
+ configResolved(config) {
15
+ root = config.root;
16
+ },
17
+ config() {
18
+ return { server: { fs: { allow: [searchForWorkspaceRoot(process.cwd()), dirname(BRIDGE_PATH)] } } };
19
+ },
20
+ transform(code, id, options) {
21
+ if (VITE_CLIENT.test(id)) {
22
+ return options?.ssr ? null : { code: `${code}\n${BRIDGE_IMPORT}\n`, map: null };
23
+ }
24
+ if (id.includes('?') || id.includes('/node_modules/') || id.startsWith('\0')) {
25
+ return null;
26
+ }
27
+ const out = injectSource(code, relative(root, id));
28
+ return out === null ? null : { code: out, map: null };
29
+ }
30
+ };
31
+ }
package/package.json CHANGED
@@ -1,6 +1,57 @@
1
1
  {
2
2
  "name": "feega-source-map",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "Dev-only plugins that tag every element with the file:line:col that wrote it, so Feega can open the source behind what you click.",
5
+ "license": "Apache-2.0",
6
+ "type": "module",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+https://github.com/andreabuttarelli/feega.git",
10
+ "directory": "packages/source-map"
11
+ },
12
+ "homepage": "https://docs.feega.app/integrations/source-map/",
13
+ "exports": {
14
+ "./vite": {
15
+ "types": "./dist/vite.d.ts",
16
+ "default": "./dist/vite.js"
17
+ },
18
+ "./next": {
19
+ "types": "./dist/next.d.ts",
20
+ "default": "./dist/next.js"
21
+ },
22
+ "./runtime": {
23
+ "types": "./dist/runtime.d.ts",
24
+ "default": "./dist/runtime.js"
25
+ },
26
+ "./bridge": {
27
+ "types": "./dist/bridge.d.ts",
28
+ "default": "./dist/bridge.js"
29
+ }
30
+ },
31
+ "files": [
32
+ "dist"
33
+ ],
34
+ "scripts": {
35
+ "build": "rm -rf dist && tsc -p tsconfig.build.json",
36
+ "prepublishOnly": "npm run build"
37
+ },
38
+ "publishConfig": {
39
+ "access": "public"
40
+ },
41
+ "dependencies": {
42
+ "@babel/parser": "^7.26.0",
43
+ "magic-string": "^0.30.0"
44
+ },
45
+ "peerDependencies": {
46
+ "svelte": ">=5",
47
+ "vite": ">=5"
48
+ },
49
+ "peerDependenciesMeta": {
50
+ "svelte": {
51
+ "optional": true
52
+ },
53
+ "vite": {
54
+ "optional": true
55
+ }
56
+ }
57
+ }