{"_id":"@andyrmitchell/dom-step-runner","_rev":"2-dd1ffbee36c87532d08c88d4f76729bb","name":"@andyrmitchell/dom-step-runner","dist-tags":{"latest":"0.1.3"},"versions":{"0.1.2":{"name":"@andyrmitchell/dom-step-runner","version":"0.1.2","author":"","license":"MIT","_id":"@andyrmitchell/dom-step-runner@0.1.2","maintainers":[{"name":"andyrmitchell","email":"a.r.mitchell@gmail.com"}],"homepage":"https://github.com/andymitchell/dom-step-runner#readme","bugs":{"url":"https://github.com/andymitchell/dom-step-runner/issues"},"dist":{"shasum":"41709550ad4da77ea6697b59c5fcb3dac1c46675","tarball":"https://registry.npmjs.org/@andyrmitchell/dom-step-runner/-/dom-step-runner-0.1.2.tgz","fileCount":5,"integrity":"sha512-cNBqkBk4u073AWbupjrc84N3YbmHfY2NdSnOyD58Q1Ta4P9B1vhXvorbKqJsKo4wxBudWPADPi3aXNMPBfwLpQ==","signatures":[{"sig":"MEUCIDQ+xfWnPMWpgq6NEWNkvvXVhXPXDJRXLzpkDvoY3jLSAiEA1fuXqZ/Ha0inqjyL97DhgAsIm/Uq6xhafE229PXTCcI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":15096},"type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"gitHead":"da7e7aa14ac50cb68b777bff1efa591ae8648114","scripts":{"test":"vitest","build":"tsup","pkglint":"./build/publint_pipeable.sh","test:watch":"vitest --watch","build_prepare":"npm run build && npm run pkglint","build_release":"npm run build_prepare && np","prepublishOnly":"npm run build_prepare"},"_npmUser":{"name":"andyrmitchell","email":"a.r.mitchell@gmail.com"},"repository":{"url":"git+https://github.com/andymitchell/dom-step-runner.git","type":"git"},"_npmVersion":"11.5.2","description":"Declarative, in-browser UI automation using serialisable JSON steps","directories":{},"_nodeVersion":"22.16.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","jsdom":"^28.1.0","vitest":"^4.0.18","typescript":"^5.9.3","@types/jest":"^30.0.0"},"_npmOperationalInternal":{"tmp":"tmp/dom-step-runner_0.1.2_1771584214272_0.9009968340030925","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"@andyrmitchell/dom-step-runner","version":"0.1.3","description":"Declarative, in-browser UI automation using serialisable JSON steps","type":"module","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"module":"./dist/index.js","types":"./dist/index.d.ts","publishConfig":{"access":"public"},"scripts":{"build_release":"npm run build_prepare && np","build":"tsup","pkglint":"./build/publint_pipeable.sh","build_prepare":"npm run build && npm run pkglint","prepublishOnly":"npm run build_prepare","test":"vitest","test:watch":"vitest --watch"},"repository":{"type":"git","url":"git+https://github.com/andymitchell/dom-step-runner.git"},"author":"","license":"MIT","devDependencies":{"@types/jest":"^30.0.0","jsdom":"^28.1.0","tsup":"^8.5.1","typescript":"^5.9.3","vitest":"^4.0.18"},"_id":"@andyrmitchell/dom-step-runner@0.1.3","gitHead":"0516d2e9c700ce77aead6bce19551d4132b39efd","bugs":{"url":"https://github.com/andymitchell/dom-step-runner/issues"},"homepage":"https://github.com/andymitchell/dom-step-runner#readme","_nodeVersion":"22.16.0","_npmVersion":"11.5.2","dist":{"integrity":"sha512-x/2vZ6ilMLAHdY7XzML/8mlqLVAZDfSHyl0Jc5Xx1tOSOVj40APNtJyqfTfYm+juAIx9/KY+abUMTC9DakwpHw==","shasum":"37a1c25e8a9eeaad0f57ea5b22fbcdd178356af7","tarball":"https://registry.npmjs.org/@andyrmitchell/dom-step-runner/-/dom-step-runner-0.1.3.tgz","fileCount":5,"unpackedSize":15096,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIE0xdiPnbFc1+lYsSscAI24nEhl5NjdHF1dTrw/7+L9qAiBqPybb39N3BFnoBnFLYzXGO8NDQ1zqU17ZTvBYsFLiCg=="}]},"_npmUser":{"name":"andyrmitchell","email":"a.r.mitchell@gmail.com"},"directories":{},"maintainers":[{"name":"andyrmitchell","email":"a.r.mitchell@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/dom-step-runner_0.1.3_1771584528722_0.6396686692397051"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-20T10:43:34.164Z","modified":"2026-02-20T10:48:48.983Z","0.1.2":"2026-02-20T10:43:34.415Z","0.1.3":"2026-02-20T10:48:48.872Z"},"bugs":{"url":"https://github.com/andymitchell/dom-step-runner/issues"},"license":"MIT","homepage":"https://github.com/andymitchell/dom-step-runner#readme","repository":{"type":"git","url":"git+https://github.com/andymitchell/dom-step-runner.git"},"description":"Declarative, in-browser UI automation using serialisable JSON steps","maintainers":[{"name":"andyrmitchell","email":"a.r.mitchell@gmail.com"}],"readme":"# `@andyrmitchell/dom-step-runner`\n\nDeclarative, in-browser UI automation using serialisable JSON steps.\n\n`DOMStepRunner` lets you **walk through a UI to reliably achieve a goal** — by describing the journey as simple, declarative steps.\n\nIt runs entirely in the browser. Perfect for Chrome extensions, dynamic control flows, scraping flows, and LLM-driven UI control.\n\n---\n\n## What It Is\n\n`DOMStepRunner` executes a sequence of **JSON-defined DOM steps**:\n\n* Wait for element\n* Click element\n* Optionally skip based on state\n* Fail cleanly if something never appears\n\nYou define *what should happen*.\nThe runner handles the timing, polling, resilience, and state transitions.\n\nThink of it as:\n\n> A lightweight, declarative UI walkthrough engine that runs directly in the browser.\n\n---\n\n## Why It’s Different\n\n### ✅ Runs Inside the Browser\n\nNo headless browser. No Puppeteer. No background server.\nWorks directly in:\n\n* Chrome extensions\n* Content scripts\n* Injected scripts\n* In-page automation\n\n---\n\n### ✅ Declarative & JSON-Based\n\nSteps are pure serialisable objects.\n\nThis means:\n\n* You can fetch updated steps from a server if the DOM changes\n* You can let an LLM generate or repair steps dynamically\n* You can store flows in a database\n* You can diff and version them\n\nUseful for brittle UIs like Gmail that change frequently.\n\n---\n\n### ✅ Designed for Dynamic UIs\n\nIt:\n\n* Waits for elements instead of sleeping blindly\n* Skips intelligently if the UI is already in the desired state\n* Handles transient UI states\n* Fails with precise diagnostics\n\n---\n\n## Core Use Cases\n\n### 1️⃣ State Preparation for Scraping\n\nExample: YouTube transcript extraction.\n\nTo scrape a transcript you must:\n\n1. Click “More”\n2. Click “Show transcript”\n3. Wait for transcript panel\n4. Then extract text\n\n`DOMStepRunner` handles the UI manipulation phase cleanly before your scraping logic runs.\n\n---\n\n### 2️⃣ UI Control (Chrome Extension Style)\n\nExample: Gmail automation.\n\nYou might want to:\n\n* Click compose\n* Wait for modal\n* Click formatting options\n* Wait for dropdown\n* Insert content\n\nInstead of imperative brittle code, define the flow declaratively.\n\nEspecially useful in Chrome Extensions where you can't update the code quickly if the DOM changes, but you can download fresh JSON to get the latest steps. \n\n---\n\n### 3️⃣ LLM-Driven Automation\n\nThe steps are a codified language for working with a page, so an LLM could define the steps and fix them when the DOM changes. \n\nAn AI can:\n\n1. Read the page\n2. Set a goal\n3. Identify necessary UI steps\n4. Output a `DOMStep[]`\n5. Run it\n6. Detect failures\n7. Repair and retry\n\n\n---\n\n# How It Works\n\n### Step 1 — Install\n\n```bash\nnpm install @andyrmitchell/dom-step-runner\n```\n\n---\n\n### Step 2 — Define Your Steps\n\nEach step describes:\n\n* What element to target\n* What action to perform\n* Optional timeout\n* Optional delay\n* Optional skip condition\n\nExample:\n\n```ts\nconst steps = [\n  {\n    name: \"Open transcript menu\",\n    target: \"button[aria-label='More actions']\",\n    action: \"click\"\n  },\n  {\n    name: \"Click show transcript\",\n    target: \"ytd-menu-service-item-renderer\",\n    action: \"click\"\n  },\n  {\n    name: \"Wait for transcript panel\",\n    target: \"#transcript\",\n    action: \"wait_for\"\n  }\n];\n```\n\n---\n\n### Step 3 — Run the Flow\n\n```ts\nimport { DOMStepRunner } from \"@andyrmitchell/dom-step-runner\";\n\nconst runner = new DOMStepRunner(true, 5000);\n\nconst result = await runner.run(steps);\n\nif (!result.success) {\n  console.error(\"Failed at:\", result.failedStepTarget);\n}\n```\n\n---\n\n### Step 4 — React to Result\n\nYou get structured failure data:\n\n```ts\n{\n  success: false,\n  message: \"Timeout waiting for '#transcript'\",\n  failedStepIndex: 2,\n  failedStepTarget: \"#transcript\"\n}\n```\n\nUse the feedback for:\n* Retry logic\n* LLM repair loops\n* Telemetry\n* Debugging UI breakages\n\n---\n\n# API Reference\n\nThis section is intended for developers and LLM agents generating flows.\n\n---\n\n## Types\n\n### `DOMStep`\n\n```ts\nexport interface DOMStep {\n  name: string;\n\n  /** CSS selector of the DOM element to interact with */\n  target: string;\n\n  /** Action to perform */\n  action: \"click\" | \"wait_for\";\n\n  /**\n   * Skip condition.\n   * 'next_available' skips this step if the NEXT step's target\n   * already exists in the DOM.\n   */\n  skipOn?: { condition: \"next_available\" };\n\n  /** Override default timeout for this step (ms) */\n  timeoutMs?: number;\n\n  /** Delay before action execution (ms) */\n  delayActionMs?: number;\n}\n```\n\n---\n\n### `DOMStepRunResult`\n\n```ts\nexport interface DOMStepRunResult {\n  success: boolean;\n  message: string;\n  failedStepIndex?: number;\n  failedStepTarget?: string;\n}\n```\n\n---\n\n## Class\n\n### `new DOMStepRunner(verbose?, defaultTimeoutMs?)`\n\n```ts\nconstructor(verbose: boolean = true, defaultTimeoutMs: number = 5000)\n```\n\n* `verbose` — Logs detailed step progression to console\n* `defaultTimeoutMs` — Default wait time for element polling\n\n---\n\n### `run(steps: DOMStep[]): Promise<DOMStepRunResult>`\n\nExecutes steps sequentially.\n\nBehavior:\n\n* Checks skip conditions\n* Waits for target element\n* Applies optional delay\n* Re-checks skip\n* Executes action\n* Fails gracefully on timeout\n\nReturns structured result object.\n\n---\n\n# Examples\n\n## Example 1 — Idempotent Modal Dismissal\n\nDismiss cookie banner only if present.\n\n```ts\nconst steps = [\n  {\n    name: \"Dismiss cookie banner\",\n    target: \"#accept-cookies\",\n    action: \"click\",\n    skipOn: { condition: \"next_available\" } // If `#app-root` already exists, the click is skipped.\n  },\n  {\n    name: \"Wait for main app\",\n    target: \"#app-root\",\n    action: \"wait_for\"\n  }\n];\n```\n\n\n\n---\n\n## Example 2 — Gmail Compose Automation\n\n```ts\nconst steps = [\n  {\n    name: \"Click Compose\",\n    target: \"div[gh='cm']\",\n    action: \"click\"\n  },\n  {\n    name: \"Wait for compose modal\",\n    target: \"div[role='dialog']\",\n    action: \"wait_for\"\n  }\n];\n```\n\n---\n\n## Example 3 — LLM-Generated Flow\n\nAn LLM might output:\n\n```json\n[\n  {\n    \"name\": \"Open menu\",\n    \"target\": \".menu-button\",\n    \"action\": \"click\"\n  },\n  {\n    \"name\": \"Wait for dropdown\",\n    \"target\": \".dropdown\",\n    \"action\": \"wait_for\"\n  }\n]\n```\n\nYour system simply:\n\n```ts\nawait runner.run(llmGeneratedSteps);\n```\n\nIf it fails:\n\n* Feed failure back to the LLM\n* Regenerate corrected steps\n* Retry\n\n---\n\n# When To Use This\n\nUse `DOMStepRunner` when:\n\n* You need reliable in-browser automation\n* You’re building Chrome extensions around changing DOMs (code is slow to update, JSON can be instant)\n* The DOM changes frequently\n* You want server-driven automation definitions\n* You’re building AI agents that manipulate UIs\n* You want deterministic, debuggable flows\n\nDo **not** use it if:\n\n* You need full browser automation across pages (use Puppeteer)\n* You need cross-origin control\n\n---\n\n# License\n\nMIT\n","readmeFilename":"README.MD"}