@vgai/editor 0.2.0

package/src/ui-source/inspect.ts

@@ -0,0 +1,544 @@
+/**
+ * Live-DOM inspection helpers (Cap 1 of the React visual-edit parity port,
+ * `docs/REACT-VISUAL-EDIT-PARITY.md`). These are `../../../visual-edit/preload.ts`'s
+ * inspection FUNCTIONS ported as DIRECT-CALL helpers.
+ *
+ * The no-iframe adaptation (see the parity spec): visual-edit injects `preload.ts` into
+ * an iframe and inspects the target app across a `postMessage` bridge. vgai mounts React
+ * worlds as DOM layers in the SAME document and `ReactWorldAuthoringAdapter` already holds
+ * the live root — so these run against the live element directly, no iframe/bridge.
+ *
+ * Headless-testable: none of these reach for a DOM global unconditionally. Fiber reads
+ * work on any object carrying a `__reactFiber$…` key (a plain fixture satisfies it).
+ * `getComputedStyles` takes a resolver (defaulting to `window.getComputedStyle` in a real
+ * browser, or the element's inline `.style` under vitest's `node` env — no jsdom).
+ * `getMatchedCssRules` takes its stylesheet list (defaulting to `document.styleSheets`).
+ */
+
+const OID_ATTR = 'data-oid';
+
+/** The ~70 most-edited CSS properties visual-edit's `getComputedStyles` captures (:73). */
+export const COMPUTED_STYLE_PROPS: readonly string[] = [
+  'width',
+  'height',
+  'minWidth',
+  'minHeight',
+  'maxWidth',
+  'maxHeight',
+  'margin',
+  'marginTop',
+  'marginRight',
+  'marginBottom',
+  'marginLeft',
+  'padding',
+  'paddingTop',
+  'paddingRight',
+  'paddingBottom',
+  'paddingLeft',
+  'display',
+  'flexDirection',
+  'flexWrap',
+  'justifyContent',
+  'alignItems',
+  'gap',
+  'flexGrow',
+  'flexShrink',
+  'flexBasis',
+  'alignSelf',
+  'position',
+  'top',
+  'right',
+  'bottom',
+  'left',
+  'backgroundColor',
+  'backgroundImage',
+  'color',
+  'fontSize',
+  'fontWeight',
+  'fontFamily',
+  'borderRadius',
+  'borderTopLeftRadius',
+  'borderTopRightRadius',
+  'borderBottomLeftRadius',
+  'borderBottomRightRadius',
+  'border',
+  'borderWidth',
+  'borderColor',
+  'borderStyle',
+  'borderTopWidth',
+  'borderRightWidth',
+  'borderBottomWidth',
+  'borderLeftWidth',
+  'borderTopStyle',
+  'borderRightStyle',
+  'borderBottomStyle',
+  'borderLeftStyle',
+  'borderTopColor',
+  'borderRightColor',
+  'borderBottomColor',
+  'borderLeftColor',
+  'opacity',
+  'overflow',
+  'zIndex',
+  'transform',
+  'mixBlendMode',
+  'filter',
+  'backdropFilter',
+  'textShadow',
+  'boxShadow',
+  'textAlign',
+  'lineHeight',
+  'letterSpacing',
+  'textTransform',
+  'textDecoration',
+  'whiteSpace',
+  'wordWrap',
+  'cursor',
+];
+
+/** camelCase CSS prop -> kebab-case (`fontSize` -> `font-size`). */
+export function camelToKebab(prop: string): string {
+  return prop.replace(/([A-Z])/g, '-$1').toLowerCase();
+}
+
+/** kebab-case CSS prop -> camelCase (`font-size` -> `fontSize`). */
+export function kebabToCamel(prop: string): string {
+  return prop.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
+}
+
+/** The minimal shape a resolved computed-style value source needs. A real
+ *  `CSSStyleDeclaration` satisfies this structurally. */
+export interface ComputedStyleLike {
+  getPropertyValue(prop: string): string;
+}
+
+/** Resolves an element to a `getPropertyValue`-capable style source (kebab keys). */
+export type ComputedStyleResolver = (el: unknown) => ComputedStyleLike;
+
+/** Read one inline style property off an element's `.style` of either shape (a real
+ *  `CSSStyleDeclaration` or a plain-object test fixture) — the same read
+ *  `react-world-authoring-adapter.ts` uses. */
+function inlineStyleProp(style: unknown, prop: string): unknown {
+  return style ? (style as Record<string, unknown>)[prop] : undefined;
+}
+
+/**
+ * The default resolver: real `window.getComputedStyle` in a browser (so CLASS-styled
+ * and CSS-file-styled properties resolve, fixing the "class-styled props show blank"
+ * bug), or — under vitest's `node` env (no `window`) — a shim reading the element's
+ * inline `.style` object, so headless fixtures keep working unchanged.
+ */
+export const browserOrInlineResolver: ComputedStyleResolver = (el) => {
+  const w = (globalThis as { window?: { getComputedStyle?: (e: unknown) => ComputedStyleLike } })
+    .window;
+  if (w?.getComputedStyle) return w.getComputedStyle(el);
+  const style = (el as { style?: unknown }).style;
+  return { getPropertyValue: (k: string) => String(inlineStyleProp(style, kebabToCamel(k)) ?? '') };
+};
+
+/**
+ * Capture the commonly-edited computed styles of an element as a camelCase-keyed record
+ * (visual-edit `getComputedStyles` :73). The resolver is injectable for headless tests;
+ * the default resolves against the live browser DOM (or inline style under `node`).
+ */
+export function getComputedStyles(
+  el: unknown,
+  resolve: ComputedStyleResolver = browserOrInlineResolver,
+): Record<string, string> {
+  const cs = resolve(el);
+  const result: Record<string, string> = {};
+  for (const p of COMPUTED_STYLE_PROPS) result[p] = cs.getPropertyValue(camelToKebab(p));
+  return result;
+}
+
+/** Read a single computed style property (camelCase), via the same resolver. */
+export function getComputedStyleValue(
+  el: unknown,
+  prop: string,
+  resolve: ComputedStyleResolver = browserOrInlineResolver,
+): string {
+  return resolve(el).getPropertyValue(camelToKebab(prop));
+}
+
+// --- React fiber inspection (visual-edit preload.ts :110/:134/:158) ---
+
+/** A minimal fiber node shape — enough for the reads below (`preload.ts` uses `any`). */
+interface FiberLike {
+  return?: FiberLike | null;
+  type?: unknown;
+  memoizedProps?: Record<string, unknown> | null;
+}
+
+/** Find the React fiber attached to a DOM element (React 18+ `__reactFiber$…`, older
+ *  `__reactInternalInstance$…`). Works on any object carrying such a key — a plain
+ *  fixture with `{ __reactFiber$x: {...} }` satisfies it headlessly. */
+export function findFiber(el: unknown): FiberLike | null {
+  if (!el || typeof el !== 'object') return null;
+  const key = Object.keys(el as object).find(
+    (k) => k.startsWith('__reactFiber$') || k.startsWith('__reactInternalInstance$'),
+  );
+  if (!key) return null;
+  return ((el as Record<string, unknown>)[key] as FiberLike) ?? null;
+}
+
+/** The parent fiber IF this element is the ROOT element of a function component
+ *  (`fiber.return` points straight at the component fiber). Else null. */
+function componentParentFiber(el: unknown): FiberLike | null {
+  const fiber = findFiber(el);
+  if (!fiber?.return) return null;
+  const parent = fiber.return;
+  return parent.type && typeof parent.type === 'function' ? parent : null;
+}
+
+/** Nearest component name for an element that is a component's root element
+ *  (visual-edit `getReactComponentName` :110). */
+export function getReactComponentName(el: unknown): string | null {
+  const parent = componentParentFiber(el);
+  if (!parent) return null;
+  const type = parent.type as { displayName?: string; name?: string };
+  return type.displayName || type.name || null;
+}
+
+/** The call-site `data-oid` prop passed to a component root (`<StatCard data-oid="x"/>`)
+ *  read off the component fiber's props (visual-edit `getCallSiteOid` :134). */
+export function getCallSiteOid(el: unknown): string | null {
+  const parent = componentParentFiber(el);
+  if (!parent) return null;
+  const v = parent.memoizedProps?.[OID_ATTR];
+  return typeof v === 'string' ? v : null;
+}
+
+/** Call-site OID for component roots, else the element's own `data-oid`
+ *  (visual-edit `getEffectiveOid` :148). */
+export function getEffectiveOid(el: { getAttribute?(name: string): string | null }): string | null {
+  return getCallSiteOid(el) ?? el.getAttribute?.(OID_ATTR) ?? null;
+}
+
+/** Primitive (string/number/boolean) props of a component root, stringified
+ *  (visual-edit `readFiberProps` :158). Skips children/key/ref/data-oid/style/className
+ *  and any non-primitive value. Returns null when there are none. */
+export function readFiberProps(el: unknown): Record<string, string> | null {
+  const parent = componentParentFiber(el);
+  if (!parent) return null;
+  const props = parent.memoizedProps;
+  if (!props || typeof props !== 'object') return null;
+
+  const SKIP = new Set(['children', 'key', 'ref', OID_ATTR, 'style', 'className']);
+  const result: Record<string, string> = {};
+  for (const [key, value] of Object.entries(props)) {
+    if (SKIP.has(key)) continue;
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+      result[key] = String(value);
+    }
+  }
+  return Object.keys(result).length > 0 ? result : null;
+}
+
+/** The component's call-site OID + its editable primitive props, or null if the element
+ *  is not a component root with props (visual-edit `getComponentProps` :463). Cap 4 feeds
+ *  the Props inspector section from this. */
+export function getComponentProps(
+  el: { getAttribute?(name: string): string | null } & unknown,
+): { callSiteOid: string; props: Record<string, string> } | null {
+  const callSiteOid = getCallSiteOid(el);
+  if (!callSiteOid) return null;
+  const props = readFiberProps(el);
+  if (!props) return null;
+  return { callSiteOid, props };
+}
+
+// --- Matched CSS rules (visual-edit preload.ts getMatchedCssRules :473) ---
+
+export interface MatchedCssRule {
+  selectorText: string;
+  properties: Record<string, string>;
+  /** The source file the owning `<style>`/`<link>` traces to (via `data-vite-dev-id`). */
+  sourceFile: string;
+}
+
+/** The minimal element shape needed to trace matched rules — `matches(selector)`. */
+export interface MatchableElement {
+  matches(selector: string): boolean;
+}
+
+/** A structural stand-in for a `CSSStyleRule` (headless-testable). */
+export interface StyleRuleLike {
+  selectorText: string;
+  style: { length: number; getPropertyValue(prop: string): string; [index: number]: string };
+}
+
+/** A structural stand-in for a `CSSStyleSheet` + its owner node. */
+export interface StyleSheetLike {
+  ownerNode?: { id?: string; getAttribute?(name: string): string | null } | null;
+  cssRules: ArrayLike<unknown>;
+}
+
+/** The id of visual-edit's own preview `<style>` tag — skipped when tracing rules. */
+const PREVIEW_STYLE_TAG_ID = '__visual-edit-preview-styles';
+
+/** Is this rule a style rule (vs `@media`/`@keyframes`)? Uses `CSSStyleRule` when the DOM
+ *  provides it, else a structural check so headless fixtures work. */
+function isStyleRule(rule: unknown): rule is StyleRuleLike {
+  const CSR = (globalThis as { CSSStyleRule?: unknown }).CSSStyleRule;
+  if (typeof CSR === 'function') return rule instanceof (CSR as new () => unknown);
+  const r = rule as Partial<StyleRuleLike>;
+  return !!r && typeof r.selectorText === 'string' && !!r.style;
+}
+
+/** Read every declared property off a style rule's declaration block. */
+function readRuleProperties(rule: StyleRuleLike): Record<string, string> {
+  const properties: Record<string, string> = {};
+  for (let i = 0; i < rule.style.length; i++) {
+    const prop = rule.style[i] as string;
+    properties[prop] = rule.style.getPropertyValue(prop);
+  }
+  return properties;
+}
+
+/**
+ * Trace the CSS rules from first-party stylesheets that MATCH an element, keyed back to
+ * their source file via the owner node's `data-vite-dev-id` (visual-edit
+ * `getMatchedCssRules` :473). Only rules from a stylesheet with a `data-vite-dev-id`
+ * (i.e. a real source file Vite is serving) are returned — Cap 2 edits those files.
+ * Sheets default to `document.styleSheets`; injectable for headless tests.
+ */
+export function getMatchedCssRules(
+  el: MatchableElement,
+  sheets: Iterable<StyleSheetLike> = (
+    globalThis as { document?: { styleSheets?: Iterable<StyleSheetLike> } }
+  ).document?.styleSheets ?? [],
+): MatchedCssRule[] {
+  const matched: MatchedCssRule[] = [];
+  for (const sheet of sheets) {
+    const owner = sheet.ownerNode;
+    if (owner?.id === PREVIEW_STYLE_TAG_ID) continue;
+    const sourceFile = owner?.getAttribute?.('data-vite-dev-id') ?? null;
+    if (!sourceFile) continue;
+    try {
+      for (const rule of Array.from(sheet.cssRules)) {
+        if (isStyleRule(rule) && el.matches(rule.selectorText)) {
+          matched.push({
+            selectorText: rule.selectorText,
+            properties: readRuleProperties(rule),
+            sourceFile,
+          });
+        }
+      }
+    } catch {
+      // Cross-origin stylesheet — its `cssRules` throws; skip it (same as visual-edit).
+    }
+  }
+  return matched;
+}
+
+// --- Design tokens (visual-edit preload.ts getDesignTokens :506) — Cap 7 ---
+
+export interface DesignToken {
+  name: string;
+  value: string;
+  category: 'color' | 'spacing' | 'other';
+}
+
+/**
+ * Enumerate the `:root` CSS custom properties (design tokens) resolved on the document
+ * root, classified color/spacing/other (visual-edit `getDesignTokens` :506). Captures
+ * Tailwind v4 `@theme`/`oklch` vars; skips Tailwind internal `--tw-*`. The computed
+ * declaration is injectable for headless tests (defaults to the live `:root`).
+ */
+export function getDesignTokens(
+  computed: (ComputedStyleLike & ArrayLike<string>) | undefined = readRootComputed(),
+): DesignToken[] {
+  if (!computed) return [];
+  const tokens: DesignToken[] = [];
+  const seen = new Set<string>();
+  for (let i = 0; i < computed.length; i++) {
+    const name = computed[i] as string;
+    if (!name.startsWith('--') || name.startsWith('--tw-') || seen.has(name)) continue;
+    seen.add(name);
+    const value = computed.getPropertyValue(name).trim();
+    if (!value) continue;
+    tokens.push({ name, value, category: classifyToken(name, value) });
+  }
+  return tokens;
+}
+
+const COLOR_VALUE_RE = /^(#[0-9a-f]{3,8}|rgba?\(|hsla?\(|oklch\()/i;
+const SPACING_NAME_RE = /spacing|gap|margin|padding|radius|size|width|height/i;
+
+/** Classify a design token by its name + value (visual-edit `getDesignTokens` :524). */
+function classifyToken(name: string, value: string): DesignToken['category'] {
+  if (/color/i.test(name) || COLOR_VALUE_RE.test(value)) return 'color';
+  if (SPACING_NAME_RE.test(name) && /^\d/.test(value)) return 'spacing';
+  return 'other';
+}
+
+// --- Cap 8: UX-polish helpers (visual-edit preload.ts getElementsInRect :635 /
+//     getSnapTargets :592 / getEmptyContainers :563 / getColorAtPoint :667 /
+//     getAvailableFonts :677). Ported as pure/injectable direct-call helpers. ---
+
+export interface Rect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** Axis-aligned rectangle intersection test (edges from x/y/width/height). */
+export function rectsIntersect(a: Rect, b: Rect): boolean {
+  if (a.x + a.width < b.x || a.x > b.x + b.width) return false;
+  if (a.y + a.height < b.y || a.y > b.y + b.height) return false;
+  return true;
+}
+
+/** A marquee candidate: an OID-tagged element's rect + the oids of its OID-tagged
+ *  descendants (for the deepest-element filter). */
+export interface MarqueeCandidate {
+  oid: string;
+  rect: Rect;
+  descendantOids: string[];
+}
+
+/**
+ * Marquee-select: the OID elements intersecting `rect`, filtered to the DEEPEST matches —
+ * an element is dropped if any of its OID descendants also matched (visual-edit
+ * `getElementsInRect` :635). Zero-area candidates are ignored. Pure; the browser wrapper
+ * builds candidates from `document.querySelectorAll('[data-oid]')`.
+ */
+export function getElementsInRect(
+  rect: Rect,
+  candidates: readonly MarqueeCandidate[],
+): { oid: string; rect: Rect }[] {
+  const hit = candidates.filter(
+    (c) => (c.rect.width > 0 || c.rect.height > 0) && rectsIntersect(c.rect, rect),
+  );
+  const hitOids = new Set(hit.map((c) => c.oid));
+  return hit
+    .filter((c) => !c.descendantOids.some((d) => d !== c.oid && hitOids.has(d)))
+    .map((c) => ({ oid: c.oid, rect: c.rect }));
+}
+
+/** Per-side padding of a container (px). */
+export interface Padding {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+/**
+ * Snap targets for dragging a child: the parent's PADDING box + its other children's rects
+ * (visual-edit `getSnapTargets` :592). Pure geometry.
+ */
+export function computeSnapTargets(
+  parentRect: Rect,
+  padding: Padding,
+  siblingRects: readonly Rect[],
+): { paddingBox: Rect; siblingRects: Rect[] } {
+  return {
+    paddingBox: {
+      x: parentRect.x + padding.left,
+      y: parentRect.y + padding.top,
+      width: parentRect.width - padding.left - padding.right,
+      height: parentRect.height - padding.top - padding.bottom,
+    },
+    siblingRects: siblingRects.filter((r) => r.width > 0 && r.height > 0),
+  };
+}
+
+/** An empty-container candidate (an OID element with no visible children/text). */
+export interface EmptyCandidate {
+  oid: string;
+  rect: Rect;
+  displayName: string;
+  hasVisibleChildren: boolean;
+  hasText: boolean;
+}
+
+/**
+ * Empty-container hint targets: OID elements with no visible children, no text, and a
+ * collapsed dimension (< 8px) — shown as a placeholder so an empty flex/grid container is
+ * still selectable (visual-edit `getEmptyContainers` :563). The placeholder rect is grown
+ * to a minimum tappable size.
+ */
+export function findEmptyContainers(
+  candidates: readonly EmptyCandidate[],
+): { oid: string; rect: Rect; displayName: string }[] {
+  const out: { oid: string; rect: Rect; displayName: string }[] = [];
+  for (const c of candidates) {
+    if (c.hasVisibleChildren || c.hasText) continue;
+    if (c.rect.width >= 8 && c.rect.height >= 8) continue;
+    out.push({
+      oid: c.oid,
+      displayName: c.displayName,
+      rect: {
+        x: c.rect.x,
+        y: c.rect.y,
+        width: Math.max(c.rect.width, 40),
+        height: Math.max(c.rect.height, 24),
+      },
+    });
+  }
+  return out;
+}
+
+const TRANSPARENT_BG = new Set(['', 'transparent', 'rgba(0, 0, 0, 0)']);
+
+/** Is a computed background color effectively transparent? */
+export function isTransparentBackground(bg: string): boolean {
+  return TRANSPARENT_BG.has(bg);
+}
+
+/**
+ * Eyedropper: the effective background color at a point — the first non-transparent
+ * background walking from the hit element up its ancestor chain, else `#fff` (visual-edit
+ * `getColorAtPoint` :667 / `getEffectiveBackground` :63). `bgChain` is hit-element-first.
+ */
+export function effectiveColorFromChain(bgChain: readonly string[]): string {
+  for (const bg of bgChain) if (!isTransparentBackground(bg)) return bg;
+  return '#fff';
+}
+
+const WEB_SAFE_FONTS = [
+  'Arial',
+  'Helvetica',
+  'Times New Roman',
+  'Georgia',
+  'Verdana',
+  'Courier New',
+  'Impact',
+  'Trebuchet MS',
+  'Palatino Linotype',
+  'Lucida Console',
+  'monospace',
+  'sans-serif',
+  'serif',
+];
+
+/** The available font families: the loaded fonts (quotes stripped) merged with the
+ *  web-safe fallbacks, de-duped and sorted (visual-edit `getAvailableFonts` :677). */
+export function mergeFonts(loaded: readonly string[] = []): string[] {
+  const fonts = new Set<string>();
+  for (const f of loaded) fonts.add(f.replace(/^["']|["']$/g, ''));
+  for (const f of WEB_SAFE_FONTS) fonts.add(f);
+  return [...fonts].sort((a, b) => a.localeCompare(b));
+}
+
+/** Browser wrapper: enumerate `document.fonts` families merged with the web-safe list.
+ *  Returns just the web-safe list under a headless (no `document.fonts`) environment. */
+export function getAvailableFonts(): string[] {
+  const g = globalThis as { document?: { fonts?: Iterable<{ family: string }> } };
+  const loaded: string[] = [];
+  const docFonts = g.document?.fonts;
+  if (docFonts) for (const f of docFonts) loaded.push(f.family);
+  return mergeFonts(loaded);
+}
+
+function readRootComputed(): (ComputedStyleLike & ArrayLike<string>) | undefined {
+  const g = globalThis as {
+    window?: { getComputedStyle?: (e: unknown) => ComputedStyleLike & ArrayLike<string> };
+    document?: { documentElement?: unknown };
+  };
+  const root = g.document?.documentElement;
+  if (!root || !g.window?.getComputedStyle) return undefined;
+  return g.window.getComputedStyle(root);
+}

package/src/ui-source/oid-transform.ts

@@ -0,0 +1,133 @@
+/**
+ * OID instrumentation (C1/C2) — the visual-edit "stamp every JSX element with a
+ * stable source id" trick, ported to vgai using the TypeScript compiler API
+ * (vgai has `typescript`; it does NOT have @babel/*). Hand-authored React UI
+ * component source is transformed at build/dev time to carry a `data-oid` on every
+ * JSX element, and an OID -> {file,line,col,component,tag} index is built so the
+ * editor can map a clicked element back to its exact source location.
+ *
+ * Stability (C1): unlike visual-edit's line:col key (which shifts every id below an
+ * edit), we key by a CONTENT signature `component:tag:nthOccurrence`, so an edit on
+ * an unrelated line keeps existing ids stable. The `data-oid` lives ONLY in the
+ * transformed output, never on disk (the writer edits the original source instead).
+ */
+import ts from 'typescript';
+
+export interface OidEntry {
+  file: string;
+  line: number; // 1-based
+  col: number; // 0-based (matches ts char)
+  component: string | null;
+  tag: string;
+}
+
+/** Persistent oid store: signature -> oid (kept stable across re-transforms). */
+export class OidStore {
+  private bySig = new Map<string, string>();
+  private counter = 0;
+  readonly index = new Map<string, OidEntry>();
+
+  getOrCreate(sig: string): string {
+    let oid = this.bySig.get(sig);
+    if (!oid) {
+      this.counter += 1;
+      oid = `o${this.counter.toString(36)}${hash(sig).toString(36)}`;
+      this.bySig.set(sig, oid);
+    }
+    return oid;
+  }
+
+  /** Clear index entries for a file before re-transforming it. */
+  clearFile(file: string): void {
+    for (const [oid, e] of this.index) if (e.file === file) this.index.delete(oid);
+  }
+}
+
+function hash(s: string): number {
+  let h = 0;
+  for (let i = 0; i < s.length; i++) h = (Math.imul(31, h) + s.charCodeAt(i)) | 0;
+  return Math.abs(h);
+}
+
+interface Insertion {
+  pos: number;
+  text: string;
+}
+
+/**
+ * Transform source: insert `data-oid="…"` on every JSX element and register the
+ * index. Returns the transformed code + the entries added for this file.
+ */
+export function transformSource(
+  code: string,
+  file: string,
+  store: OidStore,
+): { code: string; entries: OidEntry[] } {
+  const sf = ts.createSourceFile(
+    file,
+    code,
+    ts.ScriptTarget.Latest,
+    /*setParentNodes*/ true,
+    ts.ScriptKind.TSX,
+  );
+  store.clearFile(file);
+  const insertions: Insertion[] = [];
+  const entries: OidEntry[] = [];
+  const componentStack: string[] = [];
+  // per (component:tag) occurrence counters for stable signatures
+  const occ = new Map<string, number>();
+
+  const pushComponent = (name: string | undefined): boolean => {
+    if (name && /^[A-Z]/.test(name)) {
+      componentStack.push(name);
+      return true;
+    }
+    return false;
+  };
+
+  const visit = (node: ts.Node): void => {
+    let pushed = false;
+    if (ts.isFunctionDeclaration(node) && node.name) pushed = pushComponent(node.name.text);
+    else if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name))
+      pushed = pushComponent(node.name.text);
+
+    if (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) {
+      const tag = node.tagName.getText(sf);
+      const component = componentStack[componentStack.length - 1] ?? null;
+      const sigBase = `${file}:${component}:${tag}`;
+      const n = occ.get(sigBase) ?? 0;
+      occ.set(sigBase, n + 1);
+      const sig = `${sigBase}:${n}`;
+      const oid = store.getOrCreate(sig);
+      const { line, character } = sf.getLineAndCharacterOfPosition(node.getStart(sf));
+      const entry: OidEntry = { file, line: line + 1, col: character, component, tag };
+      store.index.set(oid, entry);
+      entries.push(entry);
+      // insert ` data-oid="oid"` right after the tag name
+      insertions.push({ pos: node.tagName.getEnd(), text: ` data-oid="${oid}"` });
+    }
+
+    ts.forEachChild(node, visit);
+    if (pushed) componentStack.pop();
+  };
+  visit(sf);
+
+  // apply insertions back-to-front so offsets stay valid
+  insertions.sort((a, b) => b.pos - a.pos);
+  let out = code;
+  for (const ins of insertions) out = out.slice(0, ins.pos) + ins.text + out.slice(ins.pos);
+  return { code: out, entries };
+}
+
+/** 1-based line + 0-based col -> absolute char offset in `code`. */
+export function lineColToOffset(code: string, line: number, col: number): number {
+  let offset = 0;
+  let cur = 1;
+  while (cur < line) {
+    const nl = code.indexOf('\n', offset);
+    if (nl === -1) return code.length;
+    offset = nl + 1;
+    cur += 1;
+  }
+  return offset + col;
+}