@rpascene/shared 0.30.8

package/dist/types/img/transform.d.ts

@@ -0,0 +1,88 @@
+import { Buffer } from 'node:buffer';
+import type Jimp from 'jimp';
+import type { Rect } from '../types';
+/**
+/**
+ * Saves a Base64-encoded image to a file
+ *
+ * @param options - An object containing the Base64-encoded image data and the output file path
+ * @param options.base64Data - The Base64-encoded image data
+ * @param options.outputPath - The path where the image will be saved
+ * @throws Error if there is an error during the saving process
+ */
+export declare function saveBase64Image(options: {
+    base64Data: string;
+    outputPath: string;
+}): Promise<void>;
+/**
+ * Resizes an image from Buffer, maybe return a new format
+ * - If the image is Resized, the returned format will be jpg.
+ * - If the image is not Resized, it will return to its original format.
+ * @returns { buffer: resized buffer, format: the new format}
+ */
+export declare function resizeAndConvertImgBuffer(inputFormat: string, inputData: Buffer, newSize: {
+    width: number;
+    height: number;
+}): Promise<{
+    buffer: Buffer;
+    format: string;
+}>;
+export declare const createImgBase64ByFormat: (format: string, body: string) => string;
+export declare function resizeImgBase64(inputBase64: string, newSize: {
+    width: number;
+    height: number;
+}): Promise<string>;
+/**
+ * Calculates new dimensions for an image while maintaining its aspect ratio.
+ *
+ * This function is designed to resize an image to fit within a specified maximum width and height
+ * while maintaining the original aspect ratio. If the original width or height exceeds the maximum
+ * dimensions, the image will be scaled down to fit.
+ *
+ * @param {number} originalWidth - The original width of the image.
+ * @param {number} originalHeight - The original height of the image.
+ * @returns {Object} An object containing the new width and height.
+ * @throws {Error} Throws an error if the width or height is not a positive number.
+ */
+export declare function zoomForGPT4o(originalWidth: number, originalHeight: number): {
+    width: number;
+    height: number;
+};
+export declare function jimpFromBase64(base64: string): Promise<Jimp>;
+export declare function paddingToMatchBlock(image: Jimp, blockSize?: number): Promise<{
+    width: number;
+    height: number;
+    image: Jimp;
+}>;
+export declare function paddingToMatchBlockByBase64(imageBase64: string, blockSize?: number): Promise<{
+    width: number;
+    height: number;
+    imageBase64: string;
+}>;
+export declare function cropByRect(imageBase64: string, rect: Rect, paddingImage: boolean): Promise<{
+    width: number;
+    height: number;
+    imageBase64: string;
+}>;
+export declare function jimpToBase64(image: Jimp): Promise<string>;
+export declare const httpImg2Base64: (url: string) => Promise<string>;
+/**
+ * Convert image file to base64 string
+ * Because this method is synchronous, the npm package `sharp` cannot be used to detect the file type.
+ * TODO: convert to webp to reduce base64 size.
+ */
+export declare const localImg2Base64: (imgPath: string, withoutHeader?: boolean) => string;
+/**
+ * PreProcess image url to ensure image is accessible to LLM.
+ * @param url - The url of the image, it can be a http url or a base64 string or a file path
+ * @param convertHttpImage2Base64 - Whether to convert http image to base64, if true, the http image will be converted to base64, otherwise, the http image will be returned as is
+ * @returns The base64 string of the image (when convertHttpImage2Base64 is true or url is a file path) or the http image url
+ */
+export declare const preProcessImageUrl: (url: string, convertHttpImage2Base64: boolean) => Promise<string>;
+/**
+ * parse base64 string to get mimeType and body
+ */
+export declare const parseBase64: (fullBase64String: string) => {
+    mimeType: string;
+    body: string;
+};

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export { createCopyStaticPlugin, createPlaygroundCopyPlugin, } from './build/copy-static';
+declare const _default: {};
+export default _default;

package/dist/types/logger.d.ts

@@ -0,0 +1,4 @@
+export type DebugFunction = (...args: unknown[]) => void;
+export declare function getDebug(topic: string): DebugFunction;
+export declare function enableDebug(topic: string): void;
+export declare function cleanupLogStreams(): void;

package/dist/types/node/fs.d.ts

@@ -0,0 +1,15 @@
+interface PkgInfo {
+    name: string;
+    version: string;
+    dir: string;
+}
+export declare function getRunningPkgInfo(dir?: string): PkgInfo | null;
+/**
+ * Find the nearest package.json file recursively
+ * @param {string} dir - Home directory
+ * @returns {string|null} - The most recent package.json file path or null
+ */
+export declare function findNearestPackageJson(dir: string): string | null;
+export declare function getElementInfosScriptContent(): string;
+export declare function getExtraReturnLogic(tree?: boolean): Promise<";rpascene_element_inspector.setNodeHashCacheListOnWindow();;rpascene_element_inspector.webExtractNodeTree()" | ";rpascene_element_inspector.setNodeHashCacheListOnWindow();;rpascene_element_inspector.webExtractTextWithPosition()" | null>;
+export {};

package/dist/types/node/index.d.ts

@@ -0,0 +1 @@
+export * from './fs';

package/dist/types/polyfills/async-hooks.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Browser polyfill for Node.js async_hooks module
+ * Provides empty implementation for browser environments where async_hooks is not available
+ */
+declare const AsyncLocalStorage: {};
+export { AsyncLocalStorage };

package/dist/types/polyfills/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Polyfills for Node.js modules in browser environments
+ */
+export * from './async-hooks';

package/dist/types/types/index.d.ts

@@ -0,0 +1,37 @@
+import type { NodeType } from '../constants';
+import type { ElementInfo } from '../extractor';
+export interface Point {
+    left: number;
+    top: number;
+}
+export interface Size {
+    width: number;
+    height: number;
+    dpr?: number;
+}
+export type Rect = Point & Size & {
+    zoom?: number;
+};
+export declare abstract class BaseElement {
+    abstract id: string;
+    abstract indexId?: number;
+    abstract attributes: {
+        nodeType: NodeType;
+        [key: string]: string;
+    };
+    abstract content: string;
+    abstract rect: Rect;
+    abstract center: [number, number];
+    abstract xpaths?: string[];
+    abstract isVisible: boolean;
+    abstract allPaths?: any[];
+    abstract containerPaths?: any[];
+}
+export interface ElementTreeNode<ElementType extends BaseElement = BaseElement> {
+    node: ElementType | null;
+    children: ElementTreeNode<ElementType>[];
+}
+export interface WebElementInfo extends ElementInfo {
+    zoom: number;
+    locator?: string;
+}

package/dist/types/us-keyboard-layout.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @license
+ * Copyright 2017 Google Inc.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * @internal
+ */
+export interface KeyDefinition {
+    keyCode?: number;
+    shiftKeyCode?: number;
+    key?: string;
+    shiftKey?: string;
+    code?: string;
+    text?: string;
+    shiftText?: string;
+    location?: number;
+}
+/**
+ * All the valid keys that can be passed to functions that take user input, such
+ * as {@link Keyboard.press | keyboard.press }
+ *
+ * @public
+ */
+export type KeyInput = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | 'Power' | 'Eject' | 'Abort' | 'Help' | 'Backspace' | 'Tab' | 'Numpad5' | 'NumpadEnter' | 'Enter' | '\r' | '\n' | 'ShiftLeft' | 'ShiftRight' | 'ControlLeft' | 'ControlRight' | 'AltLeft' | 'AltRight' | 'Pause' | 'CapsLock' | 'Escape' | 'Convert' | 'NonConvert' | 'Space' | 'Numpad9' | 'PageUp' | 'Numpad3' | 'PageDown' | 'End' | 'Numpad1' | 'Home' | 'Numpad7' | 'ArrowLeft' | 'Numpad4' | 'Numpad8' | 'ArrowUp' | 'ArrowRight' | 'Numpad6' | 'Numpad2' | 'ArrowDown' | 'Select' | 'Open' | 'PrintScreen' | 'Insert' | 'Numpad0' | 'Delete' | 'NumpadDecimal' | 'Digit0' | 'Digit1' | 'Digit2' | 'Digit3' | 'Digit4' | 'Digit5' | 'Digit6' | 'Digit7' | 'Digit8' | 'Digit9' | 'KeyA' | 'KeyB' | 'KeyC' | 'KeyD' | 'KeyE' | 'KeyF' | 'KeyG' | 'KeyH' | 'KeyI' | 'KeyJ' | 'KeyK' | 'KeyL' | 'KeyM' | 'KeyN' | 'KeyO' | 'KeyP' | 'KeyQ' | 'KeyR' | 'KeyS' | 'KeyT' | 'KeyU' | 'KeyV' | 'KeyW' | 'KeyX' | 'KeyY' | 'KeyZ' | 'MetaLeft' | 'MetaRight' | 'ContextMenu' | 'NumpadMultiply' | 'NumpadAdd' | 'NumpadSubtract' | 'NumpadDivide' | 'F1' | 'F2' | 'F3' | 'F4' | 'F5' | 'F6' | 'F7' | 'F8' | 'F9' | 'F10' | 'F11' | 'F12' | 'F13' | 'F14' | 'F15' | 'F16' | 'F17' | 'F18' | 'F19' | 'F20' | 'F21' | 'F22' | 'F23' | 'F24' | 'NumLock' | 'ScrollLock' | 'AudioVolumeMute' | 'AudioVolumeDown' | 'AudioVolumeUp' | 'MediaTrackNext' | 'MediaTrackPrevious' | 'MediaStop' | 'MediaPlayPause' | 'Semicolon' | 'Equal' | 'NumpadEqual' | 'Comma' | 'Minus' | 'Period' | 'Slash' | 'Backquote' | 'BracketLeft' | 'Backslash' | 'BracketRight' | 'Quote' | 'AltGraph' | 'Props' | 'Cancel' | 'Clear' | 'Shift' | 'Control' | 'Alt' | 'Accept' | 'ModeChange' | ' ' | 'Print' | 'Execute' | '\u0000' | 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z' | 'Meta' | '*' | '+' | '-' | '/' | ';' | '=' | ',' | '.' | '`' | '[' | '\\' | ']' | "'" | 'Attn' | 'CrSel' | 'ExSel' | 'EraseEof' | 'Play' | 'ZoomOut' | ')' | '!' | '@' | '#' | '$' | '%' | '^' | '&' | '(' | 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z' | ':' | '<' | '_' | '>' | '?' | '~' | '{' | '|' | '}' | '"' | 'SoftLeft' | 'SoftRight' | 'Camera' | 'Call' | 'EndCall' | 'VolumeDown' | 'VolumeUp';
+/**
+ * @internal
+ */
+export declare const _keyDefinitions: Readonly<Record<KeyInput, KeyDefinition>>;
+export declare const getKeyDefinition: (key: string) => KeyInput;
+export declare const isMac: boolean;
+export declare function transformHotkeyInput(keyInput: string): string[];

package/dist/types/utils.d.ts

@@ -0,0 +1,22 @@
+export declare const ifInBrowser: boolean;
+export declare const ifInWorker: boolean;
+export declare const ifInNode: string | false;
+export declare function uuid(): string;
+export declare function generateHashId(rect: any, content?: string): string;
+/**
+ * A utility function that asserts a condition and throws an error with a message if the condition is false.
+ *
+ * @param condition - The condition to assert
+ * @param message - The error message to throw if the condition is false
+ * @throws Error with the provided message if the condition is false
+ */
+export declare function assert(condition: any, message?: string): asserts condition;
+type GlobalScope = typeof window | typeof globalThis | typeof self | undefined;
+export declare function getGlobalScope(): GlobalScope;
+export declare function setIsMcp(value: boolean): void;
+export declare function logMsg(...message: Parameters<typeof console.log>): void;
+export declare function repeat(times: number, fn: (index: number) => Promise<void>): Promise<void>;
+export declare const escapeScriptTag: (html: string) => string;
+export declare const antiEscapeScriptTag: (html: string) => string;
+export declare function replaceIllegalPathCharsAndSpace(str: string): string;
+export {};

package/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "@rpascene/shared",
+  "version": "0.30.8",
+  "repository": "",
+  "homepage": "",
+  "types": "./dist/types/index.d.ts",
+  "main": "./dist/lib/index.js",
+  "module": "./dist/es/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/es/index.mjs",
+      "require": "./dist/lib/index.js"
+    },
+    "./constants": {
+      "types": "./dist/types/constants/index.d.ts",
+      "import": "./dist/es/constants/index.mjs",
+      "require": "./dist/lib/constants/index.js"
+    },
+    "./extractor": {
+      "types": "./dist/types/extractor/index.d.ts",
+      "import": "./dist/es/extractor/index.mjs",
+      "require": "./dist/lib/extractor/index.js"
+    },
+    "./img": {
+      "types": "./dist/types/img/index.d.ts",
+      "import": "./dist/es/img/index.mjs",
+      "require": "./dist/lib/img/index.js"
+    },
+    "./node": {
+      "types": "./dist/types/node/index.d.ts",
+      "import": "./dist/es/node/index.mjs",
+      "require": "./dist/lib/node/index.js"
+    },
+    "./types": {
+      "types": "./dist/types/types/index.d.ts",
+      "import": "./dist/es/types/index.mjs",
+      "require": "./dist/lib/types/index.js"
+    },
+    "./env": {
+      "types": "./dist/types/env/index.d.ts",
+      "import": "./dist/es/env/index.mjs",
+      "require": "./dist/lib/env/index.js"
+    },
+    "./polyfills": {
+      "types": "./dist/types/polyfills/index.d.ts",
+      "import": "./dist/es/polyfills/index.mjs",
+      "require": "./dist/lib/polyfills/index.js"
+    },
+    "./utils": {
+      "types": "./dist/types/utils.d.ts",
+      "import": "./dist/es/utils.mjs",
+      "require": "./dist/lib/utils.js"
+    },
+    "./common": {
+      "types": "./dist/types/common.d.ts",
+      "import": "./dist/es/common.mjs",
+      "require": "./dist/lib/common.js"
+    },
+    "./*": {
+      "types": "./dist/types/*.d.ts",
+      "import": "./dist/es/*.mjs",
+      "require": "./dist/lib/*.js"
+    }
+  },
+  "files": ["dist", "src", "README.md"],
+  "scripts": {
+    "dev": "npm run build:watch",
+    "build": "npm run build:script && npm run build:pkg",
+    "build:pkg": "rslib build",
+    "build:script": "rslib build -c ./rslib.inspect.config.ts",
+    "build:watch": "npm run build:script && rslib build --watch",
+    "reset": "rimraf ./**/node_modules",
+    "test": "vitest --run",
+    "test:u": "vitest --run -u"
+  },
+  "dependencies": {
+    "@silvia-odwyer/photon": "0.3.3",
+    "@silvia-odwyer/photon-node": "0.3.3",
+    "debug": "4.4.0",
+    "jimp": "0.22.12",
+    "js-sha256": "0.11.0",
+    "sharp": "^0.34.3",
+    "uuid": "11.1.0"
+  },
+  "devDependencies": {
+    "@rslib/core": "^0.11.2",
+    "@types/debug": "4.1.12",
+    "@types/node": "^18.0.0",
+    "@ui-tars/shared": "1.2.0",
+    "dotenv": "^16.4.5",
+    "rimraf": "~3.0.2",
+    "typescript": "^5.8.3",
+    "vitest": "3.0.5"
+  },
+  "sideEffects": [],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT"
+}

package/src/baseDB.ts

@@ -0,0 +1,158 @@
+// Generic database operations class
+export class IndexedDBManager {
+  private dbPromise: Promise<IDBDatabase>;
+  private dbName: string;
+  private version: number;
+  private storeConfigs: Array<{ name: string; keyPath: string }>;
+
+  constructor(
+    dbName: string,
+    version: number,
+    storeConfigs: Array<{ name: string; keyPath: string }>,
+  ) {
+    this.dbName = dbName;
+    this.version = version;
+    this.storeConfigs = storeConfigs;
+    this.dbPromise = this.initDB();
+  }
+
+  private initDB(): Promise<IDBDatabase> {
+    return new Promise((resolve, reject) => {
+      const request = indexedDB.open(this.dbName, this.version);
+
+      request.onerror = () => reject(request.error);
+      request.onsuccess = () => resolve(request.result);
+
+      request.onupgradeneeded = (event) => {
+        const db = (event.target as IDBOpenDBRequest).result;
+
+        // Create stores if they don't exist
+        this.storeConfigs.forEach(({ name, keyPath }) => {
+          if (!db.objectStoreNames.contains(name)) {
+            const store = db.createObjectStore(name, { keyPath });
+            store.createIndex('timestamp', 'timestamp', { unique: false });
+          }
+        });
+      };
+    });
+  }
+
+  private async withTransaction<T>(
+    storeNames: string | string[],
+    mode: IDBTransactionMode,
+    operation: (stores: IDBObjectStore | IDBObjectStore[]) => Promise<T>,
+  ): Promise<T> {
+    const db = await this.dbPromise;
+    const transaction = db.transaction(storeNames, mode);
+
+    const stores = Array.isArray(storeNames)
+      ? storeNames.map((name) => transaction.objectStore(name))
+      : transaction.objectStore(storeNames);
+
+    return operation(stores);
+  }
+
+  private promisifyRequest<T>(request: IDBRequest<T>): Promise<T> {
+    return new Promise((resolve, reject) => {
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  async put<T>(storeName: string, data: T): Promise<void> {
+    await this.withTransaction(storeName, 'readwrite', async (store) => {
+      await this.promisifyRequest((store as IDBObjectStore).put(data));
+    });
+  }
+
+  async get<T>(storeName: string, key: string): Promise<T | undefined> {
+    return this.withTransaction(storeName, 'readonly', async (store) => {
+      return this.promisifyRequest((store as IDBObjectStore).get(key));
+    });
+  }
+
+  async getAll<T>(storeName: string, sortByTimestamp = true): Promise<T[]> {
+    return this.withTransaction(storeName, 'readonly', async (store) => {
+      const objectStore = store as IDBObjectStore;
+      const results = sortByTimestamp
+        ? await this.promisifyRequest(objectStore.index('timestamp').getAll())
+        : await this.promisifyRequest(objectStore.getAll());
+
+      return sortByTimestamp
+        ? results.sort((a: any, b: any) => a.timestamp - b.timestamp)
+        : results;
+    });
+  }
+
+  async clear(storeName: string): Promise<void> {
+    await this.withTransaction(storeName, 'readwrite', async (store) => {
+      await this.promisifyRequest((store as IDBObjectStore).clear());
+    });
+  }
+
+  async delete(storeName: string, key: string): Promise<void> {
+    await this.withTransaction(storeName, 'readwrite', async (store) => {
+      await this.promisifyRequest((store as IDBObjectStore).delete(key));
+    });
+  }
+
+  async count(storeName: string): Promise<number> {
+    return this.withTransaction(storeName, 'readonly', async (store) => {
+      return this.promisifyRequest((store as IDBObjectStore).count());
+    });
+  }
+
+  getDBPromise(): Promise<IDBDatabase> {
+    return this.dbPromise;
+  }
+}
+
+// Generic error handler wrapper
+export const withErrorHandling = async <T>(
+  operation: () => Promise<T>,
+  errorMessage: string,
+  defaultValue?: T,
+  onQuotaExceeded?: () => Promise<void>,
+): Promise<T | undefined> => {
+  try {
+    return await operation();
+  } catch (e) {
+    console.error(errorMessage, e);
+    if (
+      e instanceof Error &&
+      e.name === 'QuotaExceededError' &&
+      onQuotaExceeded
+    ) {
+      console.log('Storage quota exceeded, running cleanup...');
+      await onQuotaExceeded();
+    }
+    return defaultValue;
+  }
+};
+
+// Base cleanup function for managing storage space
+export const createCleanupFunction = <
+  T extends { id: string; timestamp: number },
+>(
+  dbManager: IndexedDBManager,
+  storeName: string,
+  maxItems: number,
+) => {
+  return async (): Promise<void> => {
+    try {
+      const results = await dbManager.getAll<T>(storeName);
+
+      if (results.length > maxItems) {
+        const toDelete = results
+          .sort((a, b) => a.timestamp - b.timestamp)
+          .slice(0, results.length - maxItems);
+
+        await Promise.all(
+          toDelete.map((item) => dbManager.delete(storeName, item.id)),
+        );
+      }
+    } catch (e) {
+      console.error(`Failed to cleanup ${storeName}:`, e);
+    }
+  };
+};

package/src/build/copy-static.ts

@@ -0,0 +1,62 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export interface CopyStaticOptions {
+  /** Source directory to copy from */
+  srcDir: string;
+  /** Destination directory to copy to */
+  destDir: string;
+  /** Optional favicon source path (relative to directory containing srcDir) */
+  faviconPath?: string;
+  /** Name for the rsbuild plugin */
+  pluginName?: string;
+}
+
+/**
+ * Creates an rsbuild plugin that copies static files after build
+ * @param options Configuration options for copying static files
+ * @returns Rsbuild plugin object
+ */
+export const createCopyStaticPlugin = (options: CopyStaticOptions) => ({
+  name: options.pluginName || 'copy-static',
+  setup(api: any) {
+    api.onAfterBuild(async () => {
+      const { srcDir, destDir, faviconPath } = options;
+
+      await fs.promises.mkdir(destDir, { recursive: true });
+
+      // Copy directory contents recursively
+      await fs.promises.cp(srcDir, destDir, { recursive: true });
+      console.log(`Copied build artifacts from ${srcDir} to ${destDir}`);
+
+      // Copy favicon if specified
+      if (faviconPath) {
+        const faviconDest = path.join(destDir, 'favicon.ico');
+        await fs.promises.copyFile(faviconPath, faviconDest);
+        console.log(`Copied favicon from ${faviconPath} to ${faviconDest}`);
+      }
+    });
+  },
+});
+
+/**
+ * Helper function to create a copy static plugin for playground builds
+ * @param srcDir Source directory (usually dist directory)
+ * @param destDir Destination directory
+ * @param pluginName Optional plugin name
+ * @param faviconSrc Optional favicon source path
+ * @returns Rsbuild plugin
+ */
+export const createPlaygroundCopyPlugin = (
+  srcDir: string,
+  destDir: string,
+  pluginName?: string,
+  faviconSrc?: string,
+) => {
+  return createCopyStaticPlugin({
+    srcDir,
+    destDir,
+    faviconPath: faviconSrc,
+    pluginName,
+  });
+};

package/src/common.ts

@@ -0,0 +1,67 @@
+import { existsSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+// do not import getBasicEnvValue and RPASCENE_RUN_DIR directly from ./env,
+// because it will cause circular dependency
+import { getBasicEnvValue } from './env/basic';
+import { RPASCENE_RUN_DIR } from './env/types';
+import { ifInNode } from './utils';
+
+export const defaultRunDirName = 'rpascene_run';
+// Define locally for now to avoid import issues
+
+export const getRpasceneRunDir = () => {
+  if (!ifInNode) {
+    return '';
+  }
+
+  return getBasicEnvValue(RPASCENE_RUN_DIR) || defaultRunDirName;
+};
+
+export const getRpasceneRunBaseDir = () => {
+  if (!ifInNode) {
+    return '';
+  }
+
+  let basePath = path.resolve(process.cwd(), getRpasceneRunDir());
+
+  // Create a base directory
+  if (!existsSync(basePath)) {
+    try {
+      mkdirSync(basePath, { recursive: true });
+    } catch (error) {
+      // console.error(`Failed to create ${runDirName} directory: ${error}`);
+      basePath = path.join(tmpdir(), defaultRunDirName);
+      mkdirSync(basePath, { recursive: true });
+    }
+  }
+
+  return basePath;
+};
+
+/**
+ * Get the path to the rpascene_run directory or a subdirectory within it.
+ * Creates the directory if it doesn't exist.
+ *
+ * @param subdir - Optional subdirectory name (e.g., 'log', 'report')
+ * @returns The absolute path to the requested directory
+ */
+export const getRpasceneRunSubDir = (
+  subdir: 'dump' | 'cache' | 'report' | 'tmp' | 'log' | 'output',
+): string => {
+  if (!ifInNode) {
+    return '';
+  }
+
+  // Create a log directory
+  const basePath = getRpasceneRunBaseDir();
+  const logPath = path.join(basePath, subdir);
+  if (!existsSync(logPath)) {
+    mkdirSync(logPath, { recursive: true });
+  }
+
+  return logPath;
+};
+
+export const ERROR_CODE_NOT_IMPLEMENTED_AS_DESIGNED =
+  'NOT_IMPLEMENTED_AS_DESIGNED';