@designfever/web-review-kit 0.2.0 → 0.4.0

package/dist/{types-NiCp9JJQ.d.cts → types-D_qYtwTs.d.cts}

@@ -6,7 +6,7 @@ type ReviewMode = 'idle' | 'note' | 'element' | 'area';
 type ReviewSource = 'local' | 'supabase' | (string & {});
 type ReviewSubmitStatus = 'idle' | 'submitting' | 'submitted' | 'failed';
 type ReviewViewportScope = Exclude<ReviewItemScope, 'dom'>;
-type DomAnchorStrategy = 'configured-attribute' | 'id' | 'class' | 'dom-path';
+type DomAnchorStrategy = 'configured-attribute' | 'attribute' | 'id' | 'class' | 'dom-path';
 interface ReviewRulerConfig {
     enabled?: boolean;
     unit?: string;
@@ -20,6 +20,8 @@ interface DomAnchorCandidate {
 interface DomSourceHint {
     component?: string;
     file?: string;
+    line?: string;
+    column?: string;
     sectionId?: string;
     sectionIndex?: string;
 }
@@ -117,6 +119,8 @@ interface ReviewViewportPreset {
     width: number;
     height: number;
     scope?: Exclude<ReviewItemScope, 'dom'>;
+    designWidth?: number;
+    designHeight?: number;
 }
 interface NumberedReviewItem {
     item: ReviewItem;
@@ -130,6 +134,7 @@ interface WebReviewKitOptions {
     userId?: string;
     adapter?: WebReviewKitAdapter;
     target?: WebReviewKitTarget | (() => WebReviewKitTarget | undefined);
+    adjustmentLabel?: string;
     viewports?: {
         presets?: ReviewViewportPreset[];
     };

package/dist/{types-NiCp9JJQ.d.ts → types-D_qYtwTs.d.ts}

@@ -6,7 +6,7 @@ type ReviewMode = 'idle' | 'note' | 'element' | 'area';
 type ReviewSource = 'local' | 'supabase' | (string & {});
 type ReviewSubmitStatus = 'idle' | 'submitting' | 'submitted' | 'failed';
 type ReviewViewportScope = Exclude<ReviewItemScope, 'dom'>;
-type DomAnchorStrategy = 'configured-attribute' | 'id' | 'class' | 'dom-path';
+type DomAnchorStrategy = 'configured-attribute' | 'attribute' | 'id' | 'class' | 'dom-path';
 interface ReviewRulerConfig {
     enabled?: boolean;
     unit?: string;
@@ -20,6 +20,8 @@ interface DomAnchorCandidate {
 interface DomSourceHint {
     component?: string;
     file?: string;
+    line?: string;
+    column?: string;
     sectionId?: string;
     sectionIndex?: string;
 }
@@ -117,6 +119,8 @@ interface ReviewViewportPreset {
     width: number;
     height: number;
     scope?: Exclude<ReviewItemScope, 'dom'>;
+    designWidth?: number;
+    designHeight?: number;
 }
 interface NumberedReviewItem {
     item: ReviewItem;
@@ -130,6 +134,7 @@ interface WebReviewKitOptions {
     userId?: string;
     adapter?: WebReviewKitAdapter;
     target?: WebReviewKitTarget | (() => WebReviewKitTarget | undefined);
+    adjustmentLabel?: string;
     viewports?: {
         presets?: ReviewViewportPreset[];
     };

package/dist/vite.cjs

@@ -0,0 +1,186 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/vite.ts
+var vite_exports = {};
+__export(vite_exports, {
+  reviewSourceLocator: () => reviewSourceLocator
+});
+module.exports = __toCommonJS(vite_exports);
+var VIRTUAL_JSX_DEV_RUNTIME_ID = "\0@designfever/web-review-kit/source-locator/jsx-dev-runtime";
+var reviewSourceLocator = (options = {}) => {
+  let runtimeOptions = createRuntimeOptions(options);
+  return {
+    name: "df-web-review-kit-source-locator",
+    enforce: "pre",
+    configResolved(config) {
+      runtimeOptions = createRuntimeOptions(options, config);
+    },
+    resolveId(id, importer) {
+      if (!runtimeOptions.enabled) return null;
+      if (id !== "react/jsx-dev-runtime") return null;
+      if (importer === VIRTUAL_JSX_DEV_RUNTIME_ID) return null;
+      return VIRTUAL_JSX_DEV_RUNTIME_ID;
+    },
+    load(id) {
+      if (id !== VIRTUAL_JSX_DEV_RUNTIME_ID) return null;
+      return createJsxDevRuntime(runtimeOptions);
+    }
+  };
+};
+function createRuntimeOptions(options, config) {
+  const attributePrefix = (options.attributePrefix ?? "data-wrk-source").replace(
+    /-+$/,
+    ""
+  );
+  const root = normalizePath(options.root ?? config?.root ?? "");
+  const enabled = options.enabled ?? config?.command === "serve";
+  return {
+    enabled,
+    root,
+    include: (options.include ?? []).map(createRuntimeMatcher),
+    exclude: (options.exclude ?? ["node_modules", "dist"]).map(
+      createRuntimeMatcher
+    ),
+    filePath: options.filePath ?? "relative",
+    line: options.line ?? true,
+    column: options.column ?? true,
+    fileAttribute: `${attributePrefix}-file`,
+    lineAttribute: `${attributePrefix}-line`,
+    columnAttribute: `${attributePrefix}-column`
+  };
+}
+function createRuntimeMatcher(pattern) {
+  if (pattern instanceof RegExp) {
+    return { type: "regex", value: pattern.source, flags: pattern.flags };
+  }
+  return { type: "path", value: normalizePath(pattern).replace(/^\.\//, "") };
+}
+function normalizePath(value) {
+  return value.replace(/\\/g, "/").replace(/\/+$/, "");
+}
+function createJsxDevRuntime(options) {
+  return `
+import { Fragment, jsxDEV as baseJsxDEV } from 'react/jsx-dev-runtime';
+
+const OPTIONS = ${JSON.stringify(options)};
+
+export { Fragment };
+
+export function jsxDEV(type, props, key, isStaticChildren, source, self) {
+  return baseJsxDEV(
+    type,
+    injectSourceProps(type, props, source),
+    key,
+    isStaticChildren,
+    source,
+    self
+  );
+}
+
+function injectSourceProps(type, props, source) {
+  if (typeof type !== 'string') return props;
+  if (!source || typeof source.fileName !== 'string') return props;
+
+  const sourceFile = getSourceFile(source.fileName);
+  if (!sourceFile) return props;
+
+  const nextProps = props ? { ...props } : {};
+  if (nextProps[OPTIONS.fileAttribute] == null) {
+    nextProps[OPTIONS.fileAttribute] = sourceFile;
+  }
+  if (OPTIONS.line && source.lineNumber != null && nextProps[OPTIONS.lineAttribute] == null) {
+    nextProps[OPTIONS.lineAttribute] = String(source.lineNumber);
+  }
+  if (OPTIONS.column && source.columnNumber != null && nextProps[OPTIONS.columnAttribute] == null) {
+    nextProps[OPTIONS.columnAttribute] = String(source.columnNumber);
+  }
+
+  return nextProps;
+}
+
+function getSourceFile(fileName) {
+  const absoluteFile = normalizePath(fileName);
+  const relativeFile = getRelativeFile(absoluteFile);
+
+  if (OPTIONS.include.length > 0 && !matchesAny(OPTIONS.include, absoluteFile, relativeFile)) {
+    return null;
+  }
+  if (matchesAny(OPTIONS.exclude, absoluteFile, relativeFile)) return null;
+
+  return OPTIONS.filePath === 'absolute' ? absoluteFile : relativeFile;
+}
+
+function getRelativeFile(absoluteFile) {
+  if (!OPTIONS.root) return absoluteFile;
+  if (absoluteFile === OPTIONS.root) return '';
+  if (absoluteFile.startsWith(OPTIONS.root + '/')) {
+    return absoluteFile.slice(OPTIONS.root.length + 1);
+  }
+
+  return absoluteFile;
+}
+
+function matchesAny(patterns, absoluteFile, relativeFile) {
+  return patterns.some((pattern) =>
+    matchesPattern(pattern, absoluteFile, relativeFile)
+  );
+}
+
+function matchesPattern(pattern, absoluteFile, relativeFile) {
+  if (pattern.type === 'regex') {
+    const regex = new RegExp(pattern.value, pattern.flags);
+    return regex.test(absoluteFile) || regex.test(relativeFile);
+  }
+
+  const value = pattern.value;
+  const target = isAbsolutePattern(value) ? absoluteFile : relativeFile;
+  if (!value.includes('*')) {
+    return target === value || target.startsWith(value + '/');
+  }
+
+  return globToRegExp(value).test(target);
+}
+
+function isAbsolutePattern(value) {
+  return value.startsWith('/') || /^[a-zA-Z]:\\//.test(value);
+}
+
+function globToRegExp(value) {
+  const source = escapeRegExp(value)
+    .replace(/\\\\\\*\\\\\\*/g, '.*')
+    .replace(/\\\\\\*/g, '[^/]*');
+
+  return new RegExp('^' + source + '$');
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[|\\\\{}()[\\]^$+*?.]/g, '\\\\$&');
+}
+
+function normalizePath(value) {
+  return value.replace(/\\\\/g, '/').replace(/\\/+$/, '');
+}
+`;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  reviewSourceLocator
+});
+//# sourceMappingURL=vite.cjs.map

package/dist/vite.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/vite.ts"],"sourcesContent":["import type { Plugin, ResolvedConfig } from 'vite';\n\ntype SourceLocatorPattern = string | RegExp;\n\nexport interface ReviewSourceLocatorOptions {\n  enabled?: boolean;\n  root?: string;\n  include?: readonly SourceLocatorPattern[];\n  exclude?: readonly SourceLocatorPattern[];\n  filePath?: 'relative' | 'absolute';\n  line?: boolean;\n  column?: boolean;\n  attributePrefix?: string;\n}\n\ntype RuntimeMatcher =\n  | { type: 'path'; value: string }\n  | { type: 'regex'; value: string; flags: string };\n\ntype RuntimeOptions = {\n  enabled: boolean;\n  root: string;\n  include: RuntimeMatcher[];\n  exclude: RuntimeMatcher[];\n  filePath: 'relative' | 'absolute';\n  line: boolean;\n  column: boolean;\n  fileAttribute: string;\n  lineAttribute: string;\n  columnAttribute: string;\n};\n\nconst VIRTUAL_JSX_DEV_RUNTIME_ID =\n  '\\0@designfever/web-review-kit/source-locator/jsx-dev-runtime';\n\nexport const reviewSourceLocator = (\n  options: ReviewSourceLocatorOptions = {}\n): Plugin => {\n  let runtimeOptions = createRuntimeOptions(options);\n\n  return {\n    name: 'df-web-review-kit-source-locator',\n    enforce: 'pre',\n    configResolved(config) {\n      runtimeOptions = createRuntimeOptions(options, config);\n    },\n    resolveId(id, importer) {\n      if (!runtimeOptions.enabled) return null;\n      if (id !== 'react/jsx-dev-runtime') return null;\n      if (importer === VIRTUAL_JSX_DEV_RUNTIME_ID) return null;\n\n      return VIRTUAL_JSX_DEV_RUNTIME_ID;\n    },\n    load(id) {\n      if (id !== VIRTUAL_JSX_DEV_RUNTIME_ID) return null;\n      return createJsxDevRuntime(runtimeOptions);\n    },\n  };\n};\n\nfunction createRuntimeOptions(\n  options: ReviewSourceLocatorOptions,\n  config?: ResolvedConfig\n): RuntimeOptions {\n  const attributePrefix = (options.attributePrefix ?? 'data-wrk-source').replace(\n    /-+$/,\n    ''\n  );\n  const root = normalizePath(options.root ?? config?.root ?? '');\n  const enabled = options.enabled ?? (config?.command === 'serve');\n\n  return {\n    enabled,\n    root,\n    include: (options.include ?? []).map(createRuntimeMatcher),\n    exclude: (options.exclude ?? ['node_modules', 'dist']).map(\n      createRuntimeMatcher\n    ),\n    filePath: options.filePath ?? 'relative',\n    line: options.line ?? true,\n    column: options.column ?? true,\n    fileAttribute: `${attributePrefix}-file`,\n    lineAttribute: `${attributePrefix}-line`,\n    columnAttribute: `${attributePrefix}-column`,\n  };\n}\n\nfunction createRuntimeMatcher(pattern: SourceLocatorPattern): RuntimeMatcher {\n  if (pattern instanceof RegExp) {\n    return { type: 'regex', value: pattern.source, flags: pattern.flags };\n  }\n\n  return { type: 'path', value: normalizePath(pattern).replace(/^\\.\\//, '') };\n}\n\nfunction normalizePath(value: string) {\n  return value.replace(/\\\\/g, '/').replace(/\\/+$/, '');\n}\n\nfunction createJsxDevRuntime(options: RuntimeOptions) {\n  return `\nimport { Fragment, jsxDEV as baseJsxDEV } from 'react/jsx-dev-runtime';\n\nconst OPTIONS = ${JSON.stringify(options)};\n\nexport { Fragment };\n\nexport function jsxDEV(type, props, key, isStaticChildren, source, self) {\n  return baseJsxDEV(\n    type,\n    injectSourceProps(type, props, source),\n    key,\n    isStaticChildren,\n    source,\n    self\n  );\n}\n\nfunction injectSourceProps(type, props, source) {\n  if (typeof type !== 'string') return props;\n  if (!source || typeof source.fileName !== 'string') return props;\n\n  const sourceFile = getSourceFile(source.fileName);\n  if (!sourceFile) return props;\n\n  const nextProps = props ? { ...props } : {};\n  if (nextProps[OPTIONS.fileAttribute] == null) {\n    nextProps[OPTIONS.fileAttribute] = sourceFile;\n  }\n  if (OPTIONS.line && source.lineNumber != null && nextProps[OPTIONS.lineAttribute] == null) {\n    nextProps[OPTIONS.lineAttribute] = String(source.lineNumber);\n  }\n  if (OPTIONS.column && source.columnNumber != null && nextProps[OPTIONS.columnAttribute] == null) {\n    nextProps[OPTIONS.columnAttribute] = String(source.columnNumber);\n  }\n\n  return nextProps;\n}\n\nfunction getSourceFile(fileName) {\n  const absoluteFile = normalizePath(fileName);\n  const relativeFile = getRelativeFile(absoluteFile);\n\n  if (OPTIONS.include.length > 0 && !matchesAny(OPTIONS.include, absoluteFile, relativeFile)) {\n    return null;\n  }\n  if (matchesAny(OPTIONS.exclude, absoluteFile, relativeFile)) return null;\n\n  return OPTIONS.filePath === 'absolute' ? absoluteFile : relativeFile;\n}\n\nfunction getRelativeFile(absoluteFile) {\n  if (!OPTIONS.root) return absoluteFile;\n  if (absoluteFile === OPTIONS.root) return '';\n  if (absoluteFile.startsWith(OPTIONS.root + '/')) {\n    return absoluteFile.slice(OPTIONS.root.length + 1);\n  }\n\n  return absoluteFile;\n}\n\nfunction matchesAny(patterns, absoluteFile, relativeFile) {\n  return patterns.some((pattern) =>\n    matchesPattern(pattern, absoluteFile, relativeFile)\n  );\n}\n\nfunction matchesPattern(pattern, absoluteFile, relativeFile) {\n  if (pattern.type === 'regex') {\n    const regex = new RegExp(pattern.value, pattern.flags);\n    return regex.test(absoluteFile) || regex.test(relativeFile);\n  }\n\n  const value = pattern.value;\n  const target = isAbsolutePattern(value) ? absoluteFile : relativeFile;\n  if (!value.includes('*')) {\n    return target === value || target.startsWith(value + '/');\n  }\n\n  return globToRegExp(value).test(target);\n}\n\nfunction isAbsolutePattern(value) {\n  return value.startsWith('/') || /^[a-zA-Z]:\\\\//.test(value);\n}\n\nfunction globToRegExp(value) {\n  const source = escapeRegExp(value)\n    .replace(/\\\\\\\\\\\\*\\\\\\\\\\\\*/g, '.*')\n    .replace(/\\\\\\\\\\\\*/g, '[^/]*');\n\n  return new RegExp('^' + source + '$');\n}\n\nfunction escapeRegExp(value) {\n  return value.replace(/[|\\\\\\\\{}()[\\\\]^$+*?.]/g, '\\\\\\\\$&');\n}\n\nfunction normalizePath(value) {\n  return value.replace(/\\\\\\\\/g, '/').replace(/\\\\/+$/, '');\n}\n`;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAgCA,IAAM,6BACJ;AAEK,IAAM,sBAAsB,CACjC,UAAsC,CAAC,MAC5B;AACX,MAAI,iBAAiB,qBAAqB,OAAO;AAEjD,SAAO;AAAA,IACL,MAAM;AAAA,IACN,SAAS;AAAA,IACT,eAAe,QAAQ;AACrB,uBAAiB,qBAAqB,SAAS,MAAM;AAAA,IACvD;AAAA,IACA,UAAU,IAAI,UAAU;AACtB,UAAI,CAAC,eAAe,QAAS,QAAO;AACpC,UAAI,OAAO,wBAAyB,QAAO;AAC3C,UAAI,aAAa,2BAA4B,QAAO;AAEpD,aAAO;AAAA,IACT;AAAA,IACA,KAAK,IAAI;AACP,UAAI,OAAO,2BAA4B,QAAO;AAC9C,aAAO,oBAAoB,cAAc;AAAA,IAC3C;AAAA,EACF;AACF;AAEA,SAAS,qBACP,SACA,QACgB;AAChB,QAAM,mBAAmB,QAAQ,mBAAmB,mBAAmB;AAAA,IACrE;AAAA,IACA;AAAA,EACF;AACA,QAAM,OAAO,cAAc,QAAQ,QAAQ,QAAQ,QAAQ,EAAE;AAC7D,QAAM,UAAU,QAAQ,WAAY,QAAQ,YAAY;AAExD,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,UAAU,QAAQ,WAAW,CAAC,GAAG,IAAI,oBAAoB;AAAA,IACzD,UAAU,QAAQ,WAAW,CAAC,gBAAgB,MAAM,GAAG;AAAA,MACrD;AAAA,IACF;AAAA,IACA,UAAU,QAAQ,YAAY;AAAA,IAC9B,MAAM,QAAQ,QAAQ;AAAA,IACtB,QAAQ,QAAQ,UAAU;AAAA,IAC1B,eAAe,GAAG,eAAe;AAAA,IACjC,eAAe,GAAG,eAAe;AAAA,IACjC,iBAAiB,GAAG,eAAe;AAAA,EACrC;AACF;AAEA,SAAS,qBAAqB,SAA+C;AAC3E,MAAI,mBAAmB,QAAQ;AAC7B,WAAO,EAAE,MAAM,SAAS,OAAO,QAAQ,QAAQ,OAAO,QAAQ,MAAM;AAAA,EACtE;AAEA,SAAO,EAAE,MAAM,QAAQ,OAAO,cAAc,OAAO,EAAE,QAAQ,SAAS,EAAE,EAAE;AAC5E;AAEA,SAAS,cAAc,OAAe;AACpC,SAAO,MAAM,QAAQ,OAAO,GAAG,EAAE,QAAQ,QAAQ,EAAE;AACrD;AAEA,SAAS,oBAAoB,SAAyB;AACpD,SAAO;AAAA;AAAA;AAAA,kBAGS,KAAK,UAAU,OAAO,CAAC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAmGzC;","names":[]}

package/dist/vite.d.cts

@@ -0,0 +1,16 @@
+import { Plugin } from 'vite';
+
+type SourceLocatorPattern = string | RegExp;
+interface ReviewSourceLocatorOptions {
+    enabled?: boolean;
+    root?: string;
+    include?: readonly SourceLocatorPattern[];
+    exclude?: readonly SourceLocatorPattern[];
+    filePath?: 'relative' | 'absolute';
+    line?: boolean;
+    column?: boolean;
+    attributePrefix?: string;
+}
+declare const reviewSourceLocator: (options?: ReviewSourceLocatorOptions) => Plugin;
+
+export { type ReviewSourceLocatorOptions, reviewSourceLocator };

package/dist/vite.d.ts

@@ -0,0 +1,16 @@
+import { Plugin } from 'vite';
+
+type SourceLocatorPattern = string | RegExp;
+interface ReviewSourceLocatorOptions {
+    enabled?: boolean;
+    root?: string;
+    include?: readonly SourceLocatorPattern[];
+    exclude?: readonly SourceLocatorPattern[];
+    filePath?: 'relative' | 'absolute';
+    line?: boolean;
+    column?: boolean;
+    attributePrefix?: string;
+}
+declare const reviewSourceLocator: (options?: ReviewSourceLocatorOptions) => Plugin;
+
+export { type ReviewSourceLocatorOptions, reviewSourceLocator };

package/dist/vite.js

@@ -0,0 +1,161 @@
+// src/vite.ts
+var VIRTUAL_JSX_DEV_RUNTIME_ID = "\0@designfever/web-review-kit/source-locator/jsx-dev-runtime";
+var reviewSourceLocator = (options = {}) => {
+  let runtimeOptions = createRuntimeOptions(options);
+  return {
+    name: "df-web-review-kit-source-locator",
+    enforce: "pre",
+    configResolved(config) {
+      runtimeOptions = createRuntimeOptions(options, config);
+    },
+    resolveId(id, importer) {
+      if (!runtimeOptions.enabled) return null;
+      if (id !== "react/jsx-dev-runtime") return null;
+      if (importer === VIRTUAL_JSX_DEV_RUNTIME_ID) return null;
+      return VIRTUAL_JSX_DEV_RUNTIME_ID;
+    },
+    load(id) {
+      if (id !== VIRTUAL_JSX_DEV_RUNTIME_ID) return null;
+      return createJsxDevRuntime(runtimeOptions);
+    }
+  };
+};
+function createRuntimeOptions(options, config) {
+  const attributePrefix = (options.attributePrefix ?? "data-wrk-source").replace(
+    /-+$/,
+    ""
+  );
+  const root = normalizePath(options.root ?? config?.root ?? "");
+  const enabled = options.enabled ?? config?.command === "serve";
+  return {
+    enabled,
+    root,
+    include: (options.include ?? []).map(createRuntimeMatcher),
+    exclude: (options.exclude ?? ["node_modules", "dist"]).map(
+      createRuntimeMatcher
+    ),
+    filePath: options.filePath ?? "relative",
+    line: options.line ?? true,
+    column: options.column ?? true,
+    fileAttribute: `${attributePrefix}-file`,
+    lineAttribute: `${attributePrefix}-line`,
+    columnAttribute: `${attributePrefix}-column`
+  };
+}
+function createRuntimeMatcher(pattern) {
+  if (pattern instanceof RegExp) {
+    return { type: "regex", value: pattern.source, flags: pattern.flags };
+  }
+  return { type: "path", value: normalizePath(pattern).replace(/^\.\//, "") };
+}
+function normalizePath(value) {
+  return value.replace(/\\/g, "/").replace(/\/+$/, "");
+}
+function createJsxDevRuntime(options) {
+  return `
+import { Fragment, jsxDEV as baseJsxDEV } from 'react/jsx-dev-runtime';
+
+const OPTIONS = ${JSON.stringify(options)};
+
+export { Fragment };
+
+export function jsxDEV(type, props, key, isStaticChildren, source, self) {
+  return baseJsxDEV(
+    type,
+    injectSourceProps(type, props, source),
+    key,
+    isStaticChildren,
+    source,
+    self
+  );
+}
+
+function injectSourceProps(type, props, source) {
+  if (typeof type !== 'string') return props;
+  if (!source || typeof source.fileName !== 'string') return props;
+
+  const sourceFile = getSourceFile(source.fileName);
+  if (!sourceFile) return props;
+
+  const nextProps = props ? { ...props } : {};
+  if (nextProps[OPTIONS.fileAttribute] == null) {
+    nextProps[OPTIONS.fileAttribute] = sourceFile;
+  }
+  if (OPTIONS.line && source.lineNumber != null && nextProps[OPTIONS.lineAttribute] == null) {
+    nextProps[OPTIONS.lineAttribute] = String(source.lineNumber);
+  }
+  if (OPTIONS.column && source.columnNumber != null && nextProps[OPTIONS.columnAttribute] == null) {
+    nextProps[OPTIONS.columnAttribute] = String(source.columnNumber);
+  }
+
+  return nextProps;
+}
+
+function getSourceFile(fileName) {
+  const absoluteFile = normalizePath(fileName);
+  const relativeFile = getRelativeFile(absoluteFile);
+
+  if (OPTIONS.include.length > 0 && !matchesAny(OPTIONS.include, absoluteFile, relativeFile)) {
+    return null;
+  }
+  if (matchesAny(OPTIONS.exclude, absoluteFile, relativeFile)) return null;
+
+  return OPTIONS.filePath === 'absolute' ? absoluteFile : relativeFile;
+}
+
+function getRelativeFile(absoluteFile) {
+  if (!OPTIONS.root) return absoluteFile;
+  if (absoluteFile === OPTIONS.root) return '';
+  if (absoluteFile.startsWith(OPTIONS.root + '/')) {
+    return absoluteFile.slice(OPTIONS.root.length + 1);
+  }
+
+  return absoluteFile;
+}
+
+function matchesAny(patterns, absoluteFile, relativeFile) {
+  return patterns.some((pattern) =>
+    matchesPattern(pattern, absoluteFile, relativeFile)
+  );
+}
+
+function matchesPattern(pattern, absoluteFile, relativeFile) {
+  if (pattern.type === 'regex') {
+    const regex = new RegExp(pattern.value, pattern.flags);
+    return regex.test(absoluteFile) || regex.test(relativeFile);
+  }
+
+  const value = pattern.value;
+  const target = isAbsolutePattern(value) ? absoluteFile : relativeFile;
+  if (!value.includes('*')) {
+    return target === value || target.startsWith(value + '/');
+  }
+
+  return globToRegExp(value).test(target);
+}
+
+function isAbsolutePattern(value) {
+  return value.startsWith('/') || /^[a-zA-Z]:\\//.test(value);
+}
+
+function globToRegExp(value) {
+  const source = escapeRegExp(value)
+    .replace(/\\\\\\*\\\\\\*/g, '.*')
+    .replace(/\\\\\\*/g, '[^/]*');
+
+  return new RegExp('^' + source + '$');
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[|\\\\{}()[\\]^$+*?.]/g, '\\\\$&');
+}
+
+function normalizePath(value) {
+  return value.replace(/\\\\/g, '/').replace(/\\/+$/, '');
+}
+`;
+}
+export {
+  reviewSourceLocator
+};
+//# sourceMappingURL=vite.js.map

package/dist/vite.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/vite.ts"],"sourcesContent":["import type { Plugin, ResolvedConfig } from 'vite';\n\ntype SourceLocatorPattern = string | RegExp;\n\nexport interface ReviewSourceLocatorOptions {\n  enabled?: boolean;\n  root?: string;\n  include?: readonly SourceLocatorPattern[];\n  exclude?: readonly SourceLocatorPattern[];\n  filePath?: 'relative' | 'absolute';\n  line?: boolean;\n  column?: boolean;\n  attributePrefix?: string;\n}\n\ntype RuntimeMatcher =\n  | { type: 'path'; value: string }\n  | { type: 'regex'; value: string; flags: string };\n\ntype RuntimeOptions = {\n  enabled: boolean;\n  root: string;\n  include: RuntimeMatcher[];\n  exclude: RuntimeMatcher[];\n  filePath: 'relative' | 'absolute';\n  line: boolean;\n  column: boolean;\n  fileAttribute: string;\n  lineAttribute: string;\n  columnAttribute: string;\n};\n\nconst VIRTUAL_JSX_DEV_RUNTIME_ID =\n  '\\0@designfever/web-review-kit/source-locator/jsx-dev-runtime';\n\nexport const reviewSourceLocator = (\n  options: ReviewSourceLocatorOptions = {}\n): Plugin => {\n  let runtimeOptions = createRuntimeOptions(options);\n\n  return {\n    name: 'df-web-review-kit-source-locator',\n    enforce: 'pre',\n    configResolved(config) {\n      runtimeOptions = createRuntimeOptions(options, config);\n    },\n    resolveId(id, importer) {\n      if (!runtimeOptions.enabled) return null;\n      if (id !== 'react/jsx-dev-runtime') return null;\n      if (importer === VIRTUAL_JSX_DEV_RUNTIME_ID) return null;\n\n      return VIRTUAL_JSX_DEV_RUNTIME_ID;\n    },\n    load(id) {\n      if (id !== VIRTUAL_JSX_DEV_RUNTIME_ID) return null;\n      return createJsxDevRuntime(runtimeOptions);\n    },\n  };\n};\n\nfunction createRuntimeOptions(\n  options: ReviewSourceLocatorOptions,\n  config?: ResolvedConfig\n): RuntimeOptions {\n  const attributePrefix = (options.attributePrefix ?? 'data-wrk-source').replace(\n    /-+$/,\n    ''\n  );\n  const root = normalizePath(options.root ?? config?.root ?? '');\n  const enabled = options.enabled ?? (config?.command === 'serve');\n\n  return {\n    enabled,\n    root,\n    include: (options.include ?? []).map(createRuntimeMatcher),\n    exclude: (options.exclude ?? ['node_modules', 'dist']).map(\n      createRuntimeMatcher\n    ),\n    filePath: options.filePath ?? 'relative',\n    line: options.line ?? true,\n    column: options.column ?? true,\n    fileAttribute: `${attributePrefix}-file`,\n    lineAttribute: `${attributePrefix}-line`,\n    columnAttribute: `${attributePrefix}-column`,\n  };\n}\n\nfunction createRuntimeMatcher(pattern: SourceLocatorPattern): RuntimeMatcher {\n  if (pattern instanceof RegExp) {\n    return { type: 'regex', value: pattern.source, flags: pattern.flags };\n  }\n\n  return { type: 'path', value: normalizePath(pattern).replace(/^\\.\\//, '') };\n}\n\nfunction normalizePath(value: string) {\n  return value.replace(/\\\\/g, '/').replace(/\\/+$/, '');\n}\n\nfunction createJsxDevRuntime(options: RuntimeOptions) {\n  return `\nimport { Fragment, jsxDEV as baseJsxDEV } from 'react/jsx-dev-runtime';\n\nconst OPTIONS = ${JSON.stringify(options)};\n\nexport { Fragment };\n\nexport function jsxDEV(type, props, key, isStaticChildren, source, self) {\n  return baseJsxDEV(\n    type,\n    injectSourceProps(type, props, source),\n    key,\n    isStaticChildren,\n    source,\n    self\n  );\n}\n\nfunction injectSourceProps(type, props, source) {\n  if (typeof type !== 'string') return props;\n  if (!source || typeof source.fileName !== 'string') return props;\n\n  const sourceFile = getSourceFile(source.fileName);\n  if (!sourceFile) return props;\n\n  const nextProps = props ? { ...props } : {};\n  if (nextProps[OPTIONS.fileAttribute] == null) {\n    nextProps[OPTIONS.fileAttribute] = sourceFile;\n  }\n  if (OPTIONS.line && source.lineNumber != null && nextProps[OPTIONS.lineAttribute] == null) {\n    nextProps[OPTIONS.lineAttribute] = String(source.lineNumber);\n  }\n  if (OPTIONS.column && source.columnNumber != null && nextProps[OPTIONS.columnAttribute] == null) {\n    nextProps[OPTIONS.columnAttribute] = String(source.columnNumber);\n  }\n\n  return nextProps;\n}\n\nfunction getSourceFile(fileName) {\n  const absoluteFile = normalizePath(fileName);\n  const relativeFile = getRelativeFile(absoluteFile);\n\n  if (OPTIONS.include.length > 0 && !matchesAny(OPTIONS.include, absoluteFile, relativeFile)) {\n    return null;\n  }\n  if (matchesAny(OPTIONS.exclude, absoluteFile, relativeFile)) return null;\n\n  return OPTIONS.filePath === 'absolute' ? absoluteFile : relativeFile;\n}\n\nfunction getRelativeFile(absoluteFile) {\n  if (!OPTIONS.root) return absoluteFile;\n  if (absoluteFile === OPTIONS.root) return '';\n  if (absoluteFile.startsWith(OPTIONS.root + '/')) {\n    return absoluteFile.slice(OPTIONS.root.length + 1);\n  }\n\n  return absoluteFile;\n}\n\nfunction matchesAny(patterns, absoluteFile, relativeFile) {\n  return patterns.some((pattern) =>\n    matchesPattern(pattern, absoluteFile, relativeFile)\n  );\n}\n\nfunction matchesPattern(pattern, absoluteFile, relativeFile) {\n  if (pattern.type === 'regex') {\n    const regex = new RegExp(pattern.value, pattern.flags);\n    return regex.test(absoluteFile) || regex.test(relativeFile);\n  }\n\n  const value = pattern.value;\n  const target = isAbsolutePattern(value) ? absoluteFile : relativeFile;\n  if (!value.includes('*')) {\n    return target === value || target.startsWith(value + '/');\n  }\n\n  return globToRegExp(value).test(target);\n}\n\nfunction isAbsolutePattern(value) {\n  return value.startsWith('/') || /^[a-zA-Z]:\\\\//.test(value);\n}\n\nfunction globToRegExp(value) {\n  const source = escapeRegExp(value)\n    .replace(/\\\\\\\\\\\\*\\\\\\\\\\\\*/g, '.*')\n    .replace(/\\\\\\\\\\\\*/g, '[^/]*');\n\n  return new RegExp('^' + source + '$');\n}\n\nfunction escapeRegExp(value) {\n  return value.replace(/[|\\\\\\\\{}()[\\\\]^$+*?.]/g, '\\\\\\\\$&');\n}\n\nfunction normalizePath(value) {\n  return value.replace(/\\\\\\\\/g, '/').replace(/\\\\/+$/, '');\n}\n`;\n}\n"],"mappings":";AAgCA,IAAM,6BACJ;AAEK,IAAM,sBAAsB,CACjC,UAAsC,CAAC,MAC5B;AACX,MAAI,iBAAiB,qBAAqB,OAAO;AAEjD,SAAO;AAAA,IACL,MAAM;AAAA,IACN,SAAS;AAAA,IACT,eAAe,QAAQ;AACrB,uBAAiB,qBAAqB,SAAS,MAAM;AAAA,IACvD;AAAA,IACA,UAAU,IAAI,UAAU;AACtB,UAAI,CAAC,eAAe,QAAS,QAAO;AACpC,UAAI,OAAO,wBAAyB,QAAO;AAC3C,UAAI,aAAa,2BAA4B,QAAO;AAEpD,aAAO;AAAA,IACT;AAAA,IACA,KAAK,IAAI;AACP,UAAI,OAAO,2BAA4B,QAAO;AAC9C,aAAO,oBAAoB,cAAc;AAAA,IAC3C;AAAA,EACF;AACF;AAEA,SAAS,qBACP,SACA,QACgB;AAChB,QAAM,mBAAmB,QAAQ,mBAAmB,mBAAmB;AAAA,IACrE;AAAA,IACA;AAAA,EACF;AACA,QAAM,OAAO,cAAc,QAAQ,QAAQ,QAAQ,QAAQ,EAAE;AAC7D,QAAM,UAAU,QAAQ,WAAY,QAAQ,YAAY;AAExD,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,UAAU,QAAQ,WAAW,CAAC,GAAG,IAAI,oBAAoB;AAAA,IACzD,UAAU,QAAQ,WAAW,CAAC,gBAAgB,MAAM,GAAG;AAAA,MACrD;AAAA,IACF;AAAA,IACA,UAAU,QAAQ,YAAY;AAAA,IAC9B,MAAM,QAAQ,QAAQ;AAAA,IACtB,QAAQ,QAAQ,UAAU;AAAA,IAC1B,eAAe,GAAG,eAAe;AAAA,IACjC,eAAe,GAAG,eAAe;AAAA,IACjC,iBAAiB,GAAG,eAAe;AAAA,EACrC;AACF;AAEA,SAAS,qBAAqB,SAA+C;AAC3E,MAAI,mBAAmB,QAAQ;AAC7B,WAAO,EAAE,MAAM,SAAS,OAAO,QAAQ,QAAQ,OAAO,QAAQ,MAAM;AAAA,EACtE;AAEA,SAAO,EAAE,MAAM,QAAQ,OAAO,cAAc,OAAO,EAAE,QAAQ,SAAS,EAAE,EAAE;AAC5E;AAEA,SAAS,cAAc,OAAe;AACpC,SAAO,MAAM,QAAQ,OAAO,GAAG,EAAE,QAAQ,QAAQ,EAAE;AACrD;AAEA,SAAS,oBAAoB,SAAyB;AACpD,SAAO;AAAA;AAAA;AAAA,kBAGS,KAAK,UAAU,OAAO,CAAC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAmGzC;","names":[]}

package/docs/architecture.md

@@ -61,8 +61,11 @@ Persisted review data uses target-space viewport values plus optional anchor-rel
 When a user creates a DOM or area item, core tries to capture:
 
 - an explicit configured anchor such as `data-qa-id`
+- common test/section attributes such as `data-testid`, `data-cy`, or `data-section-id`
 - a meaningful `id`
+- semantic attributes such as `aria-label`, `title`, `name`, or `href`
 - a meaningful class
+- a scoped DOM path from the nearest stable ancestor
 - a DOM path fallback
 - a short text fingerprint
 

package/docs/installation.md

@@ -170,6 +170,45 @@ mountReviewShell({
 
 See [DB setup](db-setup.md) before enabling Supabase in a shared environment.
 
+## Source Locator
+
+Host projects can opt into source file hints for local QA. The Vite plugin wraps React's dev JSX runtime and writes source attributes to rendered DOM nodes.
+
+```ts
+import { defineConfig } from 'vite';
+import { reviewSourceLocator } from '@designfever/web-review-kit/vite';
+
+export default defineConfig({
+  plugins: [
+    reviewSourceLocator({
+      enabled: true,
+      include: ['src'],
+      filePath: 'absolute',
+    }),
+  ],
+});
+```
+
+Captured DOM nodes will include `data-wrk-source-file`, `data-wrk-source-line`, and `data-wrk-source-column`. In the review shell, hold `Option` over the target iframe to show source candidates from the DOM ancestry. Click the target to pin the candidate list, then choose which file to open. If the file path is absolute, it opens directly. If the plugin stores relative paths, pass `sourceRoot` when mounting the shell.
+
+```tsx
+mountReviewShell({
+  projectId: REVIEW_PROJECT_ID,
+  pages,
+  adapters,
+  reviewPathPrefix: REVIEW_PATH_PREFIX,
+  sourceRoot: import.meta.env.VITE_REVIEW_SOURCE_ROOT,
+  sourceInspector: {
+    editor: 'vscode', // 'vscode' | 'cursor' | 'webstorm' | 'custom'
+    // urlTemplate: 'my-editor://open?file={encodedPath}&line={line}&column={column}',
+  },
+});
+```
+
+Set `sourceInspector.enabled` to `false` when source code opening should be unavailable. The `data-font` overlay still belongs to the target project markup and is not required for source opening.
+
+Use this only in dev/review builds. Source paths are written into the browser DOM and can be persisted with QA items.
+
 ## Custom Adapter
 
 If a team or host project owns its own QA backend, keep that adapter in the host project or in a separate package. Start from [adaptor.sample.ts](adaptor.sample.ts) and map its `WebReviewKitAdapter` methods to your backend API.

package/docs/release-notes-0.3.0.md

@@ -0,0 +1,94 @@
+# 릴리즈 노트: 0.3.0
+
+0.2.0 mainline merge 이후 변경 사항 정리.
+
+비교 기준: `49f2665` (`Merge pull request #7 ... feat: release web review kit 0.2.0`)
+검토 기준 HEAD: `a82b204` (`release: 0.3.0`)
+
+## 주요 변경
+
+- 개발용 Vite source locator export `@designfever/web-review-kit/vite`를 추가했다.
+- DOM 리뷰 대상에 source file hint를 주입하고, 리뷰 shell에서 VS Code로 바로 여는 동작을 추가했다.
+- QA item card에서 comment를 수정할 수 있게 했다.
+- ruler 가독성, 측정 label, light theme 대비를 개선했다.
+- `data-font`를 가진 요소에 source-select font hint overlay를 표시한다.
+- 입력 필드에서 글을 쓰는 중 review hotkey가 실행되지 않도록 수정했다.
+
+## 추가
+
+### 리뷰 대상 Source Locator
+
+Host project가 Vite에서 `reviewSourceLocator()`를 선택적으로 사용할 수 있다. 이 plugin은 React dev JSX runtime을 감싸서 렌더링된 DOM node에 source attribute를 주입한다.
+
+- `data-wrk-source-file`
+- `data-wrk-source-line`
+- `data-wrk-source-column`
+
+Source hint가 있으면 review shell에서 해당 source 위치를 VS Code로 열 수 있다. 절대 경로 source path와 `sourceRoot` 기준 상대 경로를 모두 지원한다.
+
+Public package 변경:
+
+- `./vite` package export 추가
+- `src/vite.ts` 추가
+- `ReviewShellProps`에 optional `sourceRoot` 추가
+- `DomSourceHint`에 `line`, `column` 추가
+
+### Review Shell Source Action
+
+Review shell에서 다음 동작을 지원한다.
+
+- Target iframe 안에서 `Option` + click으로 클릭한 source hint 열기
+- Option key 활성화 중 source hover 표시
+- `data-font` metadata가 있는 요소의 source-select font hint overlay 표시
+- 저장된 source hint가 있는 QA card에 source open action 표시
+- Source hint가 없거나 source root가 필요한 경우 toast feedback 표시
+
+### QA Comment 수정
+
+Active adapter가 update를 지원하면 QA item card에 edit action을 표시한다. Edit modal은 빈 comment를 막고, active adapter로 저장한 뒤 review data를 새로고침하고 toast feedback을 보여준다.
+
+Adapter normalization에 `canUpdate`를 추가해서 read-only source에서는 edit action을 숨길 수 있게 했다.
+
+## 변경
+
+### Ruler UI
+
+- 측정 label을 Figma 전용 문구가 아니라 중립적인 `width x height unit` 형식으로 바꿨다.
+- Dark/light theme 모두에서 ruler label, coordinate chip, guide line, popover 가독성을 개선했다.
+- 후속 fix에서 light theme ruler 대비를 한 번 더 개선했다.
+
+### Review Shell Workflow
+
+- QA item list 정렬 기준을 `updatedAt`에서 `createdAt`으로 바꿨다. 이제 기존 item을 수정해도 목록 최상단으로 튀지 않는다.
+- Supabase list ordering도 remote source에서 같은 동작을 하도록 `created_at` 기준으로 바꿨다.
+- Quick add toolbar는 DOM element capture와 area capture 중심으로 정리했다.
+- Edit comment modal은 settings modal의 visual system을 재사용한다.
+
+### Prompt Context
+
+DOM source hint가 있으면 review item prompt에 source line context를 포함한다.
+
+## 수정
+
+- Focus가 `input`, `textarea`, `select`, `contenteditable` 안에 있을 때 review hotkey를 무시한다.
+- DOM source 추출이 새 `data-wrk-source-*` attribute와 기존 `data-file` / `data-component` 계열 attribute를 모두 읽도록 했다.
+
+## 문서
+
+- README에 public import `@designfever/web-review-kit/vite`를 문서화했다.
+- Installation docs에 source locator 설정, `sourceRoot`, source path가 DOM에 기록되는 dev/review build 주의사항을 추가했다.
+
+## 검증
+
+검토한 main branch 기준으로 아래 명령을 확인했다.
+
+- `pnpm typecheck`
+- `pnpm typecheck:dev`
+- `pnpm build`
+- `pnpm build:dev`
+
+## 메모
+
+- `package.json` version은 `0.3.0`이다.
+- `0.3.0` release commit은 `a82b204`다.
+- 이 노트를 작성한 시점에는 local/remote 모두 `0.3.0` git tag가 없었다.