@cloudcare/hvigor-ohos-plugin 0.1.0 → 0.1.2-alpha.1

package/hvigorCompile/ft-session-replay-transform.ts

@@ -0,0 +1,363 @@
+/**
+ * Guance Session Replay page-root compiler transform.
+ *
+ * ArkUI exposes a FrameNode only after a component has an ID.  The transform
+ * instruments @Entry page roots in Hvigor's in-memory source, leaving customer
+ * files untouched.  The generated calls are deliberately tiny: the optional
+ * Replay HAR owns root selection, layout retries, privacy, and capture.
+ */
+
+import { isApplicationArkTsSource } from './ft-console-log-transform';
+import { hasRuntimeDependency, SourceReader } from './ft-transform-context';
+import { allocateName as selectUniqueName } from './ft-generated-names';
+
+type TypeScriptApi = any;
+
+interface SourceRange {
+  start: number;
+  end: number;
+}
+
+interface MethodRange {
+  nameStart: number;
+  memberStart: number;
+  node: any;
+  bodyStart: number;
+  bodyEnd: number;
+}
+
+interface RootExpression {
+  end: number;
+  idArgument?: SourceRange;
+  hasAreaChange: boolean;
+  hasTouch: boolean;
+  touchArgument?: SourceRange;
+}
+
+interface EntryStruct {
+  bodyEnd: number;
+  methods: Map<string, MethodRange>;
+}
+
+interface Injection {
+  position: number;
+  content: string;
+}
+
+const REPLAY_BRIDGE_IMPORT = '@guancecloud/ft_session_replay';
+const REPLAY_ROOT_TRANSFORM_MARKER = '/* guance-session-replay-root-transform:instrumented */';
+
+function lineIndentation(code: string, position: number): string {
+  const lineStart = code.lastIndexOf('\n', position) + 1;
+  const match = code.slice(lineStart, position).match(/^\s*/);
+  return match === null ? '' : match[0];
+}
+
+function collectIdentifiers(code: string): Set<string> {
+  const identifiers = new Set<string>();
+  const expression = /\b[A-Za-z_$][A-Za-z0-9_$]*\b/g;
+  let match: RegExpExecArray | null;
+  while ((match = expression.exec(code)) !== null) {
+    identifiers.add(match[0]);
+  }
+  return identifiers;
+}
+
+/** A stable opaque source key. Do not emit customers' project paths into UI IDs. */
+function createSourceKey(id: string): string {
+  let hash = 0x811c9dc5;
+  const normalized = id.replace(/\\/g, '/').toLowerCase();
+  for (let index = 0; index < normalized.length; index++) {
+    hash ^= normalized.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0).toString(36);
+}
+
+function findImportInsertionOffset(ts: TypeScriptApi, id: string, code: string): number {
+  const sourceFile = ts.createSourceFile(id, code, ts.ScriptTarget.Latest, true,
+    ts.ScriptKind.ETS ?? ts.ScriptKind.TS);
+  let offset = 0;
+  sourceFile.statements.forEach((statement: any): void => {
+    if (ts.isImportDeclaration(statement)) {
+      offset = statement.end;
+    }
+  });
+  return offset;
+}
+
+/** Structs, decorators and members must come from the ArkTS parser, never text matches. */
+function collectEntryStructs(ts: TypeScriptApi, source: any): EntryStruct[] {
+  const entries: EntryStruct[] = [];
+  source.statements.forEach((node: any) => {
+    if (!ts.isStructDeclaration(node)) return;
+    const decorators = ts.getDecorators ? ts.getDecorators(node) || [] : node.decorators || [];
+    const isEntry = decorators.some((decorator: any) => {
+      const expression = ts.isCallExpression(decorator.expression)
+        ? decorator.expression.expression : decorator.expression;
+      return ts.isIdentifier(expression) && expression.text === 'Entry';
+    });
+    if (!isEntry) return;
+    const methods = new Map<string, MethodRange>();
+    node.members.forEach((member: any) => {
+      if (ts.isMethodDeclaration(member) && member.body && ts.isIdentifier(member.name)) {
+        methods.set(member.name.text, { nameStart: member.name.getStart(source),
+          memberStart: member.getStart(source), node: member,
+          bodyStart: member.body.getStart(source), bodyEnd: member.body.end - 1 });
+      }
+    });
+    entries.push({ bodyEnd: node.end - 1, methods });
+  });
+  return entries;
+}
+
+function componentChain(ts: TypeScriptApi, expression: any): { base: any; modifiers: any[] } {
+  const modifiers: any[] = [];
+  let base = expression;
+  while (ts.isCallExpression(base) && ts.isPropertyAccessExpression(base.expression)) {
+    modifiers.unshift(base);
+    base = base.expression.expression;
+  }
+  return { base, modifiers };
+}
+
+function argumentRange(source: any, call: any): SourceRange {
+  // Include comments and newlines before the closing parenthesis when reusing an argument.
+  return { start: call.arguments.pos, end: call.getLastToken(source).getStart(source) };
+}
+
+function findRootExpression(ts: TypeScriptApi, source: any, code: string,
+  build: MethodRange): RootExpression | null {
+  const first = build.node.body.statements[0];
+  if (!first || (!ts.isExpressionStatement(first) && !ts.isReturnStatement(first)) || !first.expression) return null;
+  const { base, modifiers } = componentChain(ts, first.expression);
+  if (!ts.isEtsComponentExpression(base) || !base.body) return null;
+  let idArgument: SourceRange | undefined;
+  let hasAreaChange = false;
+  let hasTouch = false;
+  let touchArgument: SourceRange | undefined;
+  modifiers.forEach((call: any) => {
+    const name = call.expression.name.text;
+    const range = argumentRange(source, call);
+    if (name === 'id' && call.arguments.length === 1) {
+      const argument = call.arguments[0];
+      idArgument = { start: argument.getStart(source), end: argument.end };
+    }
+    if (name === 'onAreaChange') hasAreaChange = true;
+    if (name === 'onTouch') {
+      hasTouch = true;
+      if (call.arguments.length === 1) touchArgument = range;
+    }
+  });
+  return { end: first.expression.end, idArgument, hasAreaChange, hasTouch, touchArgument };
+}
+
+function applyInjections(code: string, injections: Injection[]): string {
+  const grouped = new Map<number, string[]>();
+  injections.forEach((injection: Injection): void => {
+    const values = grouped.get(injection.position) || [];
+    values.push(injection.content);
+    grouped.set(injection.position, values);
+  });
+  const positions = Array.from(grouped.keys()).sort((left: number, right: number): number => right - left);
+  let transformed = code;
+  positions.forEach((position: number): void => {
+    transformed = transformed.slice(0, position) + (grouped.get(position) || []).join('') + transformed.slice(position);
+  });
+  return transformed;
+}
+
+function addTransitionInjections(ts: TypeScriptApi, source: any, code: string, injections: Injection[],
+  entry: EntryStruct, bridgeName: string, tokenField: string, rootExpression: string): void {
+  const method = entry.methods.get('pageTransition');
+  if (!method) {
+    const indentation = `${lineIndentation(code, entry.bodyEnd)}  `;
+    injections.push({ position: entry.bodyEnd, content: `\n${indentation}pageTransition(): void {\n` +
+      `${indentation}  if (${bridgeName}.defaultTransitionStarted(this.${tokenField})) {}\n${indentation}}\n` });
+    return;
+  }
+  let nextSpec = 0;
+  method.node.body.statements.forEach((statement: any) => {
+    if (!ts.isExpressionStatement(statement)) return;
+    const { base, modifiers } = componentChain(ts, statement.expression);
+    if ((!ts.isCallExpression(base) && !ts.isEtsComponentExpression(base)) || !ts.isIdentifier(base.expression)) return;
+    const name = base.expression.text;
+    if (name !== 'PageTransitionEnter' && name !== 'PageTransitionExit') return;
+    const entering = name === 'PageTransitionEnter';
+    const callbackName = entering ? 'onEnter' : 'onExit';
+    const spec = JSON.stringify(`transition-${nextSpec++}`);
+    const prefix = `this.${tokenField}, ${rootExpression}, ${spec}, ${entering}`;
+    let callback: SourceRange | undefined;
+    modifiers.forEach((call: any) => {
+      const modifierName = call.expression.name.text;
+      const range = argumentRange(source, call);
+      if ((modifierName === 'slide' || modifierName === 'opacity') && call.arguments.length === 1) {
+        const hook = modifierName === 'slide' ? 'transitionSlide' : 'transitionOpacity';
+        injections.push({ position: range.start,
+          content: `${bridgeName}.${hook}(this.${tokenField}, ${spec}, ` });
+        injections.push({ position: range.end, content: ')' });
+      } else if (modifierName === callbackName && call.arguments.length === 1) callback = range;
+    });
+    if (callback) {
+      injections.push({ position: callback.start, content: `${bridgeName}.wrapTransition(${prefix}, ` });
+      injections.push({ position: callback.end, content: ')' });
+    } else {
+      injections.push({ position: statement.expression.end,
+        content: `.${callbackName}((type: RouteType, progress: number) => { ${bridgeName}.transitionProgress(${prefix}, progress); })` });
+    }
+  });
+}
+
+function lifecycleCall(bridgeName: string, tokenField: string, method: 'pageShown' | 'pageHidden' | 'pageDisposed',
+  rootExpression: string, observeDefaultTransition: boolean): string {
+  if (method === 'pageShown') {
+    return `${bridgeName}.pageShown(this.getUIContext(), this.${tokenField}, ${rootExpression}, vp2px(1), ${observeDefaultTransition});`;
+  }
+  return `${bridgeName}.${method}(this.${tokenField});`;
+}
+
+function addLifecycleInjection(
+  code: string,
+  injections: Injection[],
+  struct: EntryStruct,
+  buildMethod: MethodRange,
+  bridgeName: string,
+  tokenField: string,
+  methodName: 'onPageShow' | 'onPageHide' | 'aboutToDisappear',
+  runtimeMethod: 'pageShown' | 'pageHidden' | 'pageDisposed',
+  rootExpression: string,
+  visibleField?: string
+): void {
+  const existing = struct.methods.get(methodName);
+  const rawCall = lifecycleCall(bridgeName, tokenField, runtimeMethod, rootExpression,
+    !struct.methods.has('pageTransition'));
+  const call = !visibleField ? rawCall : methodName === 'onPageShow'
+    ? `this.${visibleField} = true; if (${rootExpression}.length > 0) { ${rawCall} }`
+    : `this.${visibleField} = false; ${rawCall}`;
+  if (existing) {
+    const indentation = `${lineIndentation(code, existing.nameStart)}  `;
+    injections.push({ position: existing.bodyStart + 1, content: `\n${indentation}${call}` });
+    return;
+  }
+  const indentation = lineIndentation(code, buildMethod.nameStart);
+  injections.push({
+    position: buildMethod.memberStart,
+    content: `\n${indentation}${methodName}(): void {\n${indentation}  ${call}\n${indentation}}\n\n`
+  });
+}
+
+/**
+ * Adds an opaque root ID and page lifecycle registration to every @Entry page.
+ * ArkTS nodes locate real decorators, struct members and component expressions.
+ */
+export function transformSessionReplaySource(ts: TypeScriptApi, id: string, code: string, readSource?: SourceReader): string {
+  if (!isApplicationArkTsSource(id) || code.includes(REPLAY_ROOT_TRANSFORM_MARKER) ||
+    !hasRuntimeDependency(ts, id, '@guancecloud/ft_sdk', readSource) ||
+    !hasRuntimeDependency(ts, id, REPLAY_BRIDGE_IMPORT, readSource)) {
+    return code;
+  }
+
+  if (typeof ts.isStructDeclaration !== 'function' || typeof ts.isEtsComponentExpression !== 'function') return code;
+  // The parser needs component names to recognize declarative child blocks.
+  // This superset configures parsing only; eligibility is decided by AST nodes.
+  const components = Array.from(collectIdentifiers(code));
+  const source = ts.createSourceFile(id, code, ts.ScriptTarget.Latest, true, ts.ScriptKind.ETS,
+    { ets: {
+      components,
+      render: { method: ['build', 'pageTransition'], decorator: ['Builder', 'LocalBuilder'] },
+      extend: { decorator: ['Extend', 'AnimatableExtend'], components: components.map(name =>
+        ({ name, type: `${name}Attribute`, instance: `${name}Instance` })) },
+      styles: { decorator: 'Styles', component: { name: 'Common', type: 'T', instance: 'CommonInstance' }, property: 'stateStyles' },
+      concurrent: { decorator: 'Concurrent' },
+      customComponent: 'CustomComponent',
+      syntaxComponents: { paramsUICallback: ['ForEach', 'LazyForEach'], attrUICallback: [{ name: 'Repeat', attributes: ['each', 'template'] }] }
+    } });
+  if (source.parseDiagnostics.length > 0) return code;
+  const entries = collectEntryStructs(ts, source);
+  if (entries.length === 0) {
+    return code;
+  }
+
+  const identifiers = collectIdentifiers(code);
+  const bridgeName = selectUniqueName(identifiers, '__ftSessionReplayAutoRootBridge');
+  const tokenField = selectUniqueName(identifiers, '__ftSessionReplayRootToken');
+  const sourceKey = createSourceKey(id);
+  const injections: Injection[] = [];
+
+  entries.forEach((entry: EntryStruct): void => {
+    const buildMethod = entry.methods.get('build');
+    if (!buildMethod) {
+      return;
+    }
+    const root = findRootExpression(ts, source, code, buildMethod);
+    if (root === null) {
+      return;
+    }
+    const indentation = lineIndentation(code, buildMethod.nameStart);
+    injections.push({
+      position: buildMethod.memberStart,
+      content: `\n${indentation}private ${tokenField}: string = ${bridgeName}.createRootToken(${JSON.stringify(sourceKey)});\n\n`
+    });
+
+    let rootExpression = `this.${tokenField}`;
+    let visibleField: string | undefined;
+    if (root.idArgument) {
+      const idField = selectUniqueName(identifiers, '__ftSessionReplayRootId');
+      visibleField = selectUniqueName(identifiers, '__ftSessionReplayVisible');
+      const capture = selectUniqueName(identifiers, '__ftSessionReplayCaptureId');
+      const value = selectUniqueName(identifiers, '__ftSessionReplayIdValue');
+      rootExpression = `this.${idField}`;
+      const shown = lifecycleCall(bridgeName, tokenField, 'pageShown', rootExpression,
+        !entry.methods.has('pageTransition'));
+      injections.push({ position: buildMethod.memberStart,
+        content: `\n${indentation}private ${idField}: string = '';\n` +
+          `${indentation}private ${visibleField}: boolean = false;\n` +
+          `${indentation}private ${capture}(${value}: string): string {\n` +
+          `${indentation}  const changed: boolean = this.${idField} !== ${value};\n` +
+          `${indentation}  this.${idField} = ${value};\n` +
+          `${indentation}  if (changed && this.${visibleField} && ${value}.length > 0) { ${shown} }\n` +
+          `${indentation}  return ${value};\n${indentation}}\n` });
+      injections.push({ position: root.idArgument.start, content: `this.${capture}(` });
+      injections.push({ position: root.idArgument.end, content: ')' });
+    } else {
+      injections.push({ position: root.end, content: `.id(${rootExpression})` });
+    }
+    // Root area changes are ArkUI's public layout/draw boundary. Emit a
+    // coalesced Replay signal there instead of installing a fixed full-tree
+    // polling loop. Do not add a second modifier when an app already owns one.
+    if (!root.hasAreaChange) {
+      injections.push({
+        position: root.end,
+        content: `.onAreaChange(() => { ${bridgeName}.pageChanged(this.${tokenField}); })`
+      });
+    }
+    // Preserve application callbacks and their event propagation behavior.
+    // The bridge forwards real pointer coordinates independently of drawing.
+    if (!root.hasTouch) {
+      injections.push({
+        position: root.end,
+        content: `.onTouch((event: TouchEvent) => { ${bridgeName}.pageTouch(this.${tokenField}, event); })`
+      });
+    } else if (root.touchArgument !== undefined) {
+      injections.push({ position: root.touchArgument.start,
+        content: `${bridgeName}.wrapTouch(this.${tokenField}, ` });
+      injections.push({ position: root.touchArgument.end, content: ')' });
+    }
+    addLifecycleInjection(code, injections, entry, buildMethod, bridgeName, tokenField,
+      'onPageShow', 'pageShown', rootExpression, visibleField);
+    addLifecycleInjection(code, injections, entry, buildMethod, bridgeName, tokenField,
+      'onPageHide', 'pageHidden', rootExpression, visibleField);
+    addLifecycleInjection(code, injections, entry, buildMethod, bridgeName, tokenField,
+      'aboutToDisappear', 'pageDisposed', rootExpression, visibleField);
+    addTransitionInjections(ts, source, code, injections, entry, bridgeName, tokenField, rootExpression);
+  });
+
+  if (injections.length === 0) {
+    return code;
+  }
+  const importOffset = findImportInsertionOffset(ts, id, code);
+  const importStatement = `\n${REPLAY_ROOT_TRANSFORM_MARKER}\n` +
+    `import { FTSessionReplayAutoRootBridge as ${bridgeName} } from '${REPLAY_BRIDGE_IMPORT}';\n`;
+  injections.push({ position: importOffset, content: importStatement });
+  return applyInjections(code, injections);
+}

package/hvigorCompile/ft-source-transform-host.ts

@@ -0,0 +1,135 @@
+/**
+ * Guance compiler source-transform host.
+ *
+ * Hvigor reads ArkTS source while creating its type-checking program, before
+ * normal Rollup transforms run. This host owns that single read hook and
+ * composes feature transforms in a deterministic order. Feature modules must
+ * only transform source; they must not patch the file system themselves.
+ */
+
+import {
+  isApplicationArkTsSource,
+  transformConsoleLogSource
+} from './ft-console-log-transform';
+import { transformColdLaunchSource } from './ft-cold-launch-transform';
+import { transformSessionReplaySource } from './ft-session-replay-transform';
+import { transformWebReplaySource } from './ft-web-replay-transform';
+
+declare const require: {
+  main: {
+    require(moduleName: string): any;
+  };
+};
+
+type TypeScriptApi = any;
+type SourceReader = (fileName: string) => string | undefined;
+type SourceTransform = (ts: TypeScriptApi, fileName: string, code: string, readSource?: SourceReader) => string;
+
+interface CompilePluginContext {
+  share: {
+    projectConfig: {
+      etsLoaderPath: string;
+    };
+  };
+}
+
+interface SourceTransformDefinition {
+  id: string;
+  transform: SourceTransform;
+}
+
+interface SharedSourceTransformRegistry {
+  originalReadFile: (fileName: string, options?: any) => any;
+  buffer: any;
+  transforms: Map<string, (fileName: string, code: string) => string>;
+  owners: Map<object, Map<string, (fileName: string, code: string) => string>>;
+}
+
+const SOURCE_TRANSFORM_REGISTRY_KEY = '__guanceHvigorSourceTransformRegistry';
+const SOURCE_TRANSFORMS: SourceTransformDefinition[] = [
+  { id: 'guance-console-log-transform', transform: transformConsoleLogSource },
+  { id: 'guance-cold-launch-transform', transform: transformColdLaunchSource },
+  { id: 'guance-session-replay-root-transform', transform: transformSessionReplaySource },
+  { id: 'guance-web-replay-transform', transform: transformWebReplaySource }
+];
+
+const registrations: Array<{ fileSystem: any; owner: object; context: CompilePluginContext }> = [];
+
+function refreshTransforms(registry: SharedSourceTransformRegistry): void {
+  registry.transforms.clear();
+  registry.owners.forEach(transforms => transforms.forEach((transform, id) => registry.transforms.set(id, transform)));
+}
+
+function installSourceReader(context: CompilePluginContext): void {
+  const typeScriptPath = `${context.share.projectConfig.etsLoaderPath}/node_modules/typescript`;
+  const ts = require.main.require(typeScriptPath);
+  const fileSystem = require.main.require('fs');
+  let registry = fileSystem[SOURCE_TRANSFORM_REGISTRY_KEY] as SharedSourceTransformRegistry | undefined;
+  if (!registry) {
+    registry = {
+      originalReadFile: fileSystem.readFileSync as (fileName: string, options?: any) => any,
+      buffer: require.main.require('buffer'),
+      transforms: new Map<string, (fileName: string, code: string) => string>(),
+      owners: new Map()
+    };
+    fileSystem[SOURCE_TRANSFORM_REGISTRY_KEY] = registry;
+    fileSystem.readFileSync = (fileName: string, options?: any): any => {
+      const content = registry!.originalReadFile(fileName, options);
+      if (typeof fileName !== 'string' || !isApplicationArkTsSource(fileName)) {
+        return content;
+      }
+      let transformedCode = typeof content === 'string' ? content : content.toString();
+      registry!.transforms.forEach((transform: (id: string, code: string) => string) => {
+        transformedCode = transform(fileName, transformedCode);
+      });
+      return typeof content === 'string' ? transformedCode : registry!.buffer.Buffer.from(transformedCode);
+    };
+  }
+
+  const readSource: SourceReader = (fileName: string): string | undefined => {
+    try {
+      return registry!.originalReadFile(fileName, 'utf8').toString();
+    } catch (_) {
+      return undefined;
+    }
+  };
+  const owner = {};
+  const transforms = new Map<string, (fileName: string, code: string) => string>();
+  SOURCE_TRANSFORMS.forEach((definition: SourceTransformDefinition) => {
+    transforms.set(definition.id, (fileName: string, code: string) =>
+      definition.transform(ts, fileName, code, readSource));
+  });
+  registry.owners.set(owner, transforms);
+  refreshTransforms(registry);
+  registrations.push({ fileSystem, owner, context });
+}
+
+function restoreSourceReader(context: CompilePluginContext): void {
+  let index = registrations.length - 1;
+  for (let candidate = registrations.length - 1; candidate >= 0; candidate--) {
+    if (registrations[candidate].context === context) { index = candidate; break; }
+  }
+  const registration = index < 0 ? undefined : registrations.splice(index, 1)[0];
+  if (!registration) return;
+  const { fileSystem, owner } = registration;
+  const registry = fileSystem[SOURCE_TRANSFORM_REGISTRY_KEY] as SharedSourceTransformRegistry | undefined;
+  if (registry) {
+    registry.owners.delete(owner);
+    refreshTransforms(registry);
+    if (registry.owners.size === 0) {
+      fileSystem.readFileSync = registry.originalReadFile;
+      delete fileSystem[SOURCE_TRANSFORM_REGISTRY_KEY];
+    }
+  }
+}
+
+export default {
+  name: 'guance-source-transform-host',
+  order: 'first',
+  buildStart(this: CompilePluginContext): void {
+    installSourceReader(this);
+  },
+  buildEnd(this: CompilePluginContext): void {
+    restoreSourceReader(this);
+  }
+};

package/hvigorCompile/ft-transform-context.ts

@@ -0,0 +1,36 @@
+/** Shared, source-module-specific guards for compiler transforms. */
+declare const require: any;
+
+export type SourceReader = (fileName: string) => string | undefined;
+
+export function objectProperty(ts: any, object: any, name: string): any | undefined {
+  if (!object || !ts.isObjectLiteralExpression(object)) return undefined;
+  const matches = object.properties.filter((item: any) => ts.isPropertyAssignment(item) &&
+    (ts.isIdentifier(item.name) || ts.isStringLiteral(item.name)) && item.name.text === name);
+  return matches.length > 0 ? matches[matches.length - 1].initializer : undefined;
+}
+
+/** Read JSON5 as data syntax, without evaluating package contents. */
+export function hasRuntimeDependency(ts: any, id: string, packageName: string, readSource?: SourceReader): boolean {
+  const normalized = id.replace(/\\/g, '/');
+  const sourceIndex = normalized.lastIndexOf('/src/main/ets/');
+  if (sourceIndex < 0) return false;
+  const packagePath = normalized.slice(0, sourceIndex) + '/oh-package.json5';
+  try {
+    const nodeRequire = require.main && typeof require.main.require === 'function'
+      ? require.main.require.bind(require.main) : require;
+    const code = readSource ? readSource(packagePath) : nodeRequire('fs').readFileSync(packagePath, 'utf8');
+    if (typeof code !== 'string') return false;
+    const parsed = ts.createSourceFile(packagePath, `const __package = ${code}`,
+      ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    if (parsed.parseDiagnostics.length > 0 || parsed.statements.length !== 1 ||
+      !ts.isVariableStatement(parsed.statements[0])) return false;
+    const root = parsed.statements[0].declarationList.declarations[0].initializer;
+    const dependency = objectProperty(ts, objectProperty(ts, root, 'dependencies'), packageName);
+    // Runtime imports require an explicit dependency in the owning module.
+    // Do not inherit the entry/root module's dependencies or match comments/devDependencies.
+    return !!dependency && ts.isStringLiteral(dependency) && dependency.text.trim().length > 0;
+  } catch (_) {
+    return false;
+  }
+}

package/hvigorCompile/ft-web-replay-transform.ts

@@ -0,0 +1,51 @@
+/** Associate every native Web with its controller without replacing application IDs or callbacks. */
+import { isApplicationArkTsSource } from './ft-console-log-transform';
+import { hasRuntimeDependency, SourceReader } from './ft-transform-context';
+import { createLexicalResolver } from './ft-lexical-scope';
+import { allocateName, collectIdentifierNames } from './ft-generated-names';
+
+type TypeScriptApi = any;
+interface Injection { position: number; content: string; }
+
+const MARKER = '/* guance-web-replay-transform:instrumented */';
+const SDK_IMPORT = '@guancecloud/ft_sdk/Index';
+
+export function transformWebReplaySource(ts: TypeScriptApi, id: string, code: string, readSource?: SourceReader): string {
+  if (!isApplicationArkTsSource(id) || code.includes(MARKER) ||
+    !hasRuntimeDependency(ts, id, '@guancecloud/ft_sdk', readSource) ||
+    !hasRuntimeDependency(ts, id, '@guancecloud/ft_session_replay', readSource)) return code;
+
+  const source = ts.createSourceFile(id, code, ts.ScriptTarget.Latest, true, ts.ScriptKind.ETS ?? ts.ScriptKind.TS);
+  const identifiers = collectIdentifierNames(ts, source);
+  const constructors: any[] = [];
+  const resolve = createLexicalResolver(ts, source);
+  let importEnd = 0;
+  const visit = (node: any): void => {
+    if (ts.isImportDeclaration(node)) importEnd = Math.max(importEnd, node.end);
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === 'Web' &&
+      node.arguments.length === 1 && !ts.isSpreadElement(node.arguments[0]) &&
+      !resolve(node.expression, 'Web')) constructors.push(node);
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  if (constructors.length === 0) return code;
+
+  const bridge = allocateName(identifiers, '__ftWebReplayBridge');
+  const injections: Injection[] = [];
+  for (const constructor of constructors) {
+    const options = constructor.arguments[0];
+    // Keep the pair adjacent, before any app modifier expression can evaluate another Web.
+    injections.push({ position: options.getStart(source), content: `${bridge}.prepare(` });
+    injections.push({ position: options.end, content: ')' });
+    injections.push({ position: constructor.end,
+      content: `.customProperty(${bridge}.PROPERTY, ${bridge}.consumeBindingId())` });
+  }
+  injections.push({ position: importEnd,
+    content: `\n${MARKER}\nimport { FTWebViewReplayBridge as ${bridge} } from '${SDK_IMPORT}';\n` });
+  injections.sort((left, right) => right.position - left.position);
+  let result = code;
+  for (const injection of injections) {
+    result = result.slice(0, injection.position) + injection.content + result.slice(injection.position);
+  }
+  return result;
+}

package/index.js

@@ -4,21 +4,21 @@ const path = require('path');
 const { OhosPluginId } = require('@ohos/hvigor-ohos-plugin');
 
 /**
- * Returns the HAP-level Hvigor plugin used to instrument console/HiLog calls
- * and cold-launch lifecycle boundaries before ArkTS compilation.
+ * Returns the HAP-level Hvigor plugin used to instrument console/HiLog calls,
+ * cold-launch lifecycle boundaries, Session Replay page roots and Web bindings before
+ * ArkTS compilation.
  *
  * This package intentionally contains build tooling only. Applications still
- * need @guancecloud/ft_sdk at runtime to receive the instrumented log calls.
+ * need their matching runtime HARs to receive instrumented calls. The Replay
+ * transform self-disables when @guancecloud/ft_session_replay is absent.
  */
 function ftConsoleLogPlugin() {
   return {
     pluginId: 'guance-console-log-compiler',
     apply(node) {
       const hapContext = node.getContext(OhosPluginId.OHOS_HAP_PLUGIN);
-      const consoleLogTransformPath = path.join(__dirname, 'hvigorCompile', 'ft-console-log-transform.ts');
-      const coldLaunchTransformPath = path.join(__dirname, 'hvigorCompile', 'ft-cold-launch-transform.ts');
-      hapContext.loadCompilePlugin(consoleLogTransformPath);
-      hapContext.loadCompilePlugin(coldLaunchTransformPath);
+      const sourceTransformHostPath = path.join(__dirname, 'hvigorCompile', 'ft-source-transform-host.ts');
+      hapContext.loadCompilePlugin(sourceTransformHostPath);
     }
   };
 }

package/package.json

@@ -1,12 +1,18 @@
 {
   "name": "@cloudcare/hvigor-ohos-plugin",
-  "version": "0.1.0",
-  "description": "Guance HarmonyOS Hvigor plugin for automatic console, HiLog, and cold-launch collection.",
+  "version": "0.1.2-alpha.1",
+  "description": "Guance HarmonyOS Hvigor plugin for console, cold-launch, Session Replay page roots, and Web controller binding.",
   "main": "index.js",
   "files": [
     "index.js",
+    "hvigorCompile/ft-source-transform-host.ts",
+    "hvigorCompile/ft-transform-context.ts",
+    "hvigorCompile/ft-lexical-scope.ts",
+    "hvigorCompile/ft-generated-names.ts",
     "hvigorCompile/ft-console-log-transform.ts",
     "hvigorCompile/ft-cold-launch-transform.ts",
+    "hvigorCompile/ft-session-replay-transform.ts",
+    "hvigorCompile/ft-web-replay-transform.ts",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -26,11 +32,15 @@
     "node": ">=18"
   },
   "peerDependencies": {
-    "@guancecloud/ft_sdk": ">=0.1.17"
+    "@guancecloud/ft_sdk": ">=0.1.17",
+    "@guancecloud/ft_session_replay": ">=0.1.0-alpha01"
   },
   "peerDependenciesMeta": {
     "@guancecloud/ft_sdk": {
       "optional": true
+    },
+    "@guancecloud/ft_session_replay": {
+      "optional": true
     }
   }
 }