aetherius 0.2.0__py3-none-any.whl

aetherius/recorder/_overlay_js.py

@@ -0,0 +1,262 @@
+"""The recorder's floating "mod menu": an in-page overlay to pick data and pose meta-actions.
+
+Injected like the debug overlay (``add_init_script``, re-installed on every navigation), but isolated
+in a Shadow DOM so the page's CSS cannot mangle it and vice versa. It hosts a toolbar (Pick data /
+Pick table / Wait for / Make input / Finish); a hover highlight; and small panels to choose the
+extraction format. Element descriptors and selectors come from the shared ``window.__aeSel``
+(:mod:`._selector_js`); the ranking policy stays pure Python (:mod:`.selector_synth`).
+
+All emit paths funnel through ``window.__aeOverlay.{emitExtract,emitRecords,emitWaitFor,emitParam}``,
+which the UI calls and integration tests drive directly (so the payload contract is testable without
+replaying the whole click-through). While any mode is active, ``window.__aeRecorderPicking`` tells the
+action-capture script to stand down.
+"""
+
+from __future__ import annotations
+
+# Self-invoking, guarded. Requires window.__aeSel (inject SELECTOR_JS first). Emits through the same
+# __aetherius_capture binding as action capture, with pick/records/wait_for/parameterize/finish kinds.
+OVERLAY_JS = r"""
+(() => {
+  if (window.__aeOverlay) return;
+  const OVERLAY_ID = '__ae-recorder-overlay';
+  const ACCENT = '#c9a94a';
+
+  const send = (p) => { try { window.__aetherius_capture(JSON.stringify(p)); } catch (e) {} };
+  const S = () => window.__aeSel;
+
+  const STATUS = {
+    idle: 'Idle — pick a tool.',
+    pick: 'Pick data: click an element to extract.',
+    table: 'Pick table: click the repeating item, then each field, then Done.',
+    waitfor: 'Wait for: click the element to wait for.',
+    makeinput: 'Make input: click a field you filled to parameterize it.',
+  };
+
+  let host, root, statusEl, panelEl, highlight, doneBtn;
+  let mode = 'idle';
+  let container = null;   // repeating-record container element (table mode)
+  let fields = [];        // [{name, el, as, attr}]
+
+  const guessType = (el) => {
+    const tag = el.tagName.toLowerCase();
+    if (tag === 'img') return { as: 'attr', attr: 'src' };
+    if (tag === 'a') return { as: 'attr', attr: 'href' };
+    const t = (el.textContent || '').trim();
+    if (t && t.length < 24 && /\d/.test(t) && /^[^A-Za-z]*-?\d/.test(t)) return { as: 'number', attr: '' };
+    return { as: 'text', attr: '' };
+  };
+
+  const guessName = (el) => {
+    const raw = el.getAttribute('data-testid') || el.id || el.getAttribute('name') ||
+      (S().visibleText(el) || '') || el.tagName.toLowerCase();
+    return raw.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '').slice(0, 24) || 'field';
+  };
+
+  // ── Emit API (called by the UI and by integration tests) ──────────────────
+  window.__aeOverlay = {
+    emitExtract(el, cfg) {
+      // `group` (matches all siblings) is used when as is list/count; single values use the
+      // unique selector Python synthesizes from the descriptor.
+      send({ kind: 'extract', descriptor: S().descriptorFor(el), name: cfg.name, as: cfg.as,
+             attr: cfg.attr || null, item: cfg.item || null, group: S().groupSelector(el) });
+    },
+    emitRecords(cont, fieldDefs, name) {
+      send({ kind: 'extract_records', descriptor: S().descriptorFor(cont), name,
+             each: S().groupSelector(cont),
+             fields: fieldDefs.map((f) => ({
+               name: f.name, selector: S().relativeSelector(cont, f.el),
+               as: f.as || 'text', attr: f.attr || null })) });
+    },
+    emitWaitFor(el) {
+      // group selector fallback: waiting is a presence check, so a class that matches the whole
+      // group beats a brittle positional path when the element has no unique hook.
+      send({ kind: 'wait_for', descriptor: S().descriptorFor(el), group: S().groupSelector(el) });
+    },
+    emitParam(el, name) { send({ kind: 'parameterize', descriptor: S().descriptorFor(el), name }); },
+    setMode: (m) => setMode(m),
+  };
+
+  // ── UI ─────────────────────────────────────────────────────────────────────
+  const el = (tag, css, text) => {
+    const n = document.createElement(tag);
+    if (css) n.style.cssText = css;
+    if (text != null) n.textContent = text;
+    return n;
+  };
+
+  const button = (label, onclick) => {
+    const b = el('button',
+      'margin:0 4px 0 0;padding:4px 8px;font:12px system-ui;cursor:pointer;border-radius:5px;' +
+      'border:1px solid ' + ACCENT + '55;background:#1c1830;color:#e7e2f3;', label);
+    b.addEventListener('click', (e) => { e.preventDefault(); e.stopPropagation(); onclick(); });
+    return b;
+  };
+
+  const clearPanel = () => { if (panelEl) panelEl.innerHTML = ''; };
+
+  const setMode = (m) => {
+    mode = m;
+    window.__aeRecorderPicking = (m !== 'idle');
+    if (statusEl) statusEl.textContent = STATUS[m] || '';
+    if (highlight) highlight.style.display = (m === 'idle') ? 'none' : 'block';
+    if (doneBtn) doneBtn.style.display = (m === 'table') ? 'inline-block' : 'none';
+    if (m === 'idle') { clearPanel(); container = null; fields = []; }
+  };
+
+  const fieldRow = (labelText, node) => {
+    const row = el('div', 'display:flex;align-items:center;gap:6px;margin:4px 0;');
+    row.appendChild(el('label', 'font:12px system-ui;color:#b9b2d0;min-width:64px;', labelText));
+    row.appendChild(node);
+    return row;
+  };
+
+  const textInput = (value) => {
+    const i = el('input', 'flex:1;padding:3px 6px;font:12px system-ui;border-radius:4px;' +
+      'border:1px solid #4a4368;background:#0f0b1e;color:#e7e2f3;');
+    i.value = value || '';
+    return i;
+  };
+
+  const typeSelect = (value) => {
+    const s = el('select', 'padding:3px;font:12px system-ui;border-radius:4px;' +
+      'border:1px solid #4a4368;background:#0f0b1e;color:#e7e2f3;');
+    for (const t of ['text', 'number', 'html', 'attr', 'count']) {
+      const o = el('option', '', t); o.value = t; if (t === value) o.selected = true; s.appendChild(o);
+    }
+    return s;
+  };
+
+  // Format panel for a single element (Pick data).
+  const openFormPanel = (target) => {
+    clearPanel();
+    const g = guessType(target);
+    const name = textInput(guessName(target));
+    const type = typeSelect(g.as);
+    const attr = textInput(g.attr);
+    const attrRow = fieldRow('attr', attr);
+    const allBox = el('input'); allBox.type = 'checkbox';
+    const sync = () => { attrRow.style.display = (type.value === 'attr') ? 'flex' : 'none'; };
+    type.addEventListener('change', sync);
+
+    panelEl.appendChild(fieldRow('name', name));
+    panelEl.appendChild(fieldRow('type', type));
+    panelEl.appendChild(attrRow);
+    panelEl.appendChild(fieldRow('all matching', allBox));
+    const actions = el('div', 'margin-top:6px;');
+    actions.appendChild(button('Add', () => {
+      const asList = allBox.checked && type.value !== 'count';
+      const as = asList ? 'list' : type.value;
+      window.__aeOverlay.emitExtract(target, { name: name.value, as,
+        attr: type.value === 'attr' ? attr.value : '', item: asList ? type.value : null });
+      setMode('idle');
+    }));
+    actions.appendChild(button('Cancel', () => setMode('idle')));
+    panelEl.appendChild(actions);
+    sync();
+  };
+
+  // Field panel for a record field (Pick table, after the container is chosen).
+  const openFieldPanel = (target) => {
+    clearPanel();
+    const g = guessType(target);
+    const name = textInput(guessName(target));
+    const type = typeSelect(g.as === 'count' ? 'text' : g.as);
+    panelEl.appendChild(el('div', 'font:12px system-ui;color:' + ACCENT + ';', 'Record field'));
+    panelEl.appendChild(fieldRow('name', name));
+    panelEl.appendChild(fieldRow('type', type));
+    const actions = el('div', 'margin-top:6px;');
+    actions.appendChild(button('Add field', () => {
+      fields.push({ name: name.value, el: target, as: type.value, attr: g.attr });
+      statusEl.textContent = fields.length + ' field(s) — click more, then Done.';
+      clearPanel();
+    }));
+    panelEl.appendChild(actions);
+  };
+
+  const openInputPanel = (target) => {
+    clearPanel();
+    const name = textInput(guessName(target));
+    panelEl.appendChild(fieldRow('input name', name));
+    const actions = el('div', 'margin-top:6px;');
+    actions.appendChild(button('Make input', () => {
+      window.__aeOverlay.emitParam(target, name.value); setMode('idle');
+    }));
+    actions.appendChild(button('Cancel', () => setMode('idle')));
+    panelEl.appendChild(actions);
+  };
+
+  const targetOf = (e) => {
+    const path = e.composedPath ? e.composedPath() : [e.target];
+    if (path.some((n) => n && n.id === OVERLAY_ID)) return null;  // never target the overlay
+    return e.target;
+  };
+
+  const onMove = (e) => {
+    if (mode === 'idle' || !highlight) return;
+    const t = targetOf(e);
+    if (!t || !t.getBoundingClientRect) { highlight.style.display = 'none'; return; }
+    const r = t.getBoundingClientRect();
+    highlight.style.display = 'block';
+    highlight.style.left = r.left + 'px'; highlight.style.top = r.top + 'px';
+    highlight.style.width = r.width + 'px'; highlight.style.height = r.height + 'px';
+  };
+
+  const onClick = (e) => {
+    if (mode === 'idle') return;
+    const t = targetOf(e);
+    if (!t) return;  // clicks on the overlay's own controls fall through to their handlers
+    e.preventDefault(); e.stopPropagation();
+    if (mode === 'pick') { openFormPanel(t); }
+    else if (mode === 'waitfor') { window.__aeOverlay.emitWaitFor(t); setMode('idle'); }
+    else if (mode === 'makeinput') { openInputPanel(t); }
+    else if (mode === 'table') {
+      if (!container) { container = t; statusEl.textContent = 'Container set — click each field.'; }
+      else { openFieldPanel(t); }
+    }
+  };
+
+  const install = () => {
+    const rootEl = document.documentElement;
+    if (!rootEl || document.getElementById(OVERLAY_ID)) return;
+    host = el('div'); host.id = OVERLAY_ID;
+    host.style.cssText = 'all:initial;position:fixed;z-index:2147483647;';
+    rootEl.appendChild(host);
+    root = host.attachShadow({ mode: 'open' });
+
+    highlight = el('div', 'position:fixed;z-index:2147483646;pointer-events:none;display:none;' +
+      'border:2px solid ' + ACCENT + ';background:' + ACCENT + '22;box-sizing:border-box;');
+    root.appendChild(highlight);
+
+    const bar = el('div', 'position:fixed;top:10px;right:10px;width:270px;padding:8px 10px;' +
+      'font:12px system-ui;background:#171327ee;color:#e7e2f3;border:1px solid ' + ACCENT + '66;' +
+      'border-radius:8px;box-shadow:0 6px 24px #000a;');
+    const title = el('div', 'font-weight:600;color:' + ACCENT + ';margin-bottom:6px;', 'Aetherius recorder');
+    const tools = el('div', 'margin-bottom:6px;');
+    tools.appendChild(button('Pick data', () => setMode('pick')));
+    tools.appendChild(button('Pick table', () => setMode('table')));
+    tools.appendChild(button('Wait for', () => setMode('waitfor')));
+    tools.appendChild(button('Make input', () => setMode('makeinput')));
+    doneBtn = button('Done', () => {
+      if (container && fields.length) window.__aeOverlay.emitRecords(container, fields, 'records');
+      setMode('idle');
+    });
+    doneBtn.style.display = 'none';
+    tools.appendChild(doneBtn);
+    tools.appendChild(button('Finish', () => { setMode('idle'); send({ kind: 'finish' }); }));
+    statusEl = el('div', 'color:#b9b2d0;min-height:16px;', STATUS.idle);
+    panelEl = el('div', 'margin-top:6px;');
+    bar.appendChild(title); bar.appendChild(tools); bar.appendChild(statusEl); bar.appendChild(panelEl);
+    root.appendChild(bar);
+
+    document.addEventListener('mousemove', onMove, true);
+    document.addEventListener('click', onClick, true);
+  };
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', install);
+  } else {
+    install();
+  }
+})();
+"""

aetherius/recorder/_playwright.py

@@ -0,0 +1,49 @@
+"""Shared Playwright plumbing for the recorders: lazy import and the synchronous pump loop.
+
+Both recorders drive a visible browser and collect callbacks that the sync Playwright API only
+dispatches while a Playwright call is in flight. They share the same lazy import (so ``import
+aetherius`` stays light and a missing extra is a typed error) and the same idle pump, kept here once.
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Any
+
+from ..core.errors import DependencyError
+
+# How often the pump wakes to let the sync Playwright API dispatch pending binding/event callbacks.
+_PUMP_INTERVAL_MS = 200
+
+
+def import_playwright() -> Any:
+    """Import the sync Playwright entry point, or raise a typed, actionable error."""
+    try:
+        from playwright.sync_api import sync_playwright
+    except ImportError as exc:  # extra [browser] not installed
+        raise DependencyError(
+            "The recorder requires Playwright. Install it with:\n"
+            '    pip install "aetherius[browser]" && playwright install chromium',
+            extra="browser",
+        ) from exc
+    return sync_playwright
+
+
+def pump(context: Any, disconnected: threading.Event, *stop_events: threading.Event | None) -> None:
+    """Keep the sync API alive so callbacks fire, until the window closes or a stop event is set.
+
+    Several stop events are accepted (e.g. the caller's Stop and the overlay's Finish); any one ends
+    the loop. ``None`` entries are ignored so callers can pass optional events directly.
+    """
+    while not disconnected.is_set() and not any(_is_set(e) for e in stop_events):
+        pages = context.pages
+        if not pages:
+            break
+        try:
+            pages[0].wait_for_timeout(_PUMP_INTERVAL_MS)
+        except Exception:  # the page or context went away: the demonstration is over
+            break
+
+
+def _is_set(event: threading.Event | None) -> bool:
+    return event is not None and event.is_set()

aetherius/recorder/_selector_js.py

@@ -0,0 +1,148 @@
+"""Shared in-page selector primitives, installed on ``window.__aeSel``.
+
+The only place that can call ``CSS.escape`` and measure a selector's uniqueness against the live DOM.
+Both the action-capture script (:mod:`._capture_js`) and the pick overlay (:mod:`._overlay_js`) build
+their element descriptors from here, so the candidate/uniqueness logic exists once. The ranking policy
+that turns candidates into a Blueprint selector stays pure Python (:mod:`.selector_synth`).
+"""
+
+from __future__ import annotations
+
+# Self-invoking, guarded. Attaches the primitives to window so later scripts can reuse them.
+SELECTOR_JS = r"""
+(() => {
+  if (window.__aeSel) return;
+
+  const CLICKABLE = 'a, button, [role="button"], input[type="submit"], input[type="button"], ' +
+    'input[type="reset"], input[type="checkbox"], input[type="radio"]';
+
+  const isUnique = (sel, root) => {
+    try { return (root || document).querySelectorAll(sel).length === 1; } catch (e) { return false; }
+  };
+
+  // Escape a value for use inside an [attr="..."] string: only backslash and double-quote.
+  // (CSS.escape is for identifiers like #id/.class and would over-escape `/`, spaces, etc.)
+  const attrValue = (v) => String(v).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+
+  const testIdAttr = (el) => {
+    for (const name of ['data-testid', 'data-test', 'data-cy', 'data-qa']) {
+      if (el.hasAttribute(name)) return [name, el.getAttribute(name)];
+    }
+    return null;
+  };
+
+  const cssPath = (el) => {
+    const parts = [];
+    let node = el;
+    while (node && node.nodeType === 1 && node !== document.body) {
+      let part = node.tagName.toLowerCase();
+      if (node.id) { parts.unshift('#' + CSS.escape(node.id)); break; }
+      const parent = node.parentElement;
+      if (parent) {
+        const sameTag = [...parent.children].filter((c) => c.tagName === node.tagName);
+        if (sameTag.length > 1) part += ':nth-of-type(' + (sameTag.indexOf(node) + 1) + ')';
+      }
+      parts.unshift(part);
+      node = node.parentElement;
+    }
+    return parts.join(' > ');
+  };
+
+  const visibleText = (el) => {
+    const t = (el.textContent || '').trim().replace(/\s+/g, ' ');
+    return t.length > 0 && t.length <= 64 ? t : null;
+  };
+
+  const candidates = (el) => {
+    const tag = el.tagName.toLowerCase();
+    const out = [];
+    const push = (strategy, selector, selector_type) =>
+      out.push({ strategy, selector, selector_type, unique: isUnique(selector) });
+
+    const testId = testIdAttr(el);
+    if (testId) push('testid', '[' + testId[0] + '="' + attrValue(testId[1]) + '"]', 'css');
+    if (el.id) push('id', '#' + CSS.escape(el.id), 'css');
+    const href = tag === 'a' ? el.getAttribute('href') : null;  // the natural, stable hook for a link
+    if (href) push('href', 'a[href="' + attrValue(href) + '"]', 'css');
+    const name = el.getAttribute('name');
+    if (name) push('name', tag + '[name="' + attrValue(name) + '"]', 'css');
+    const aria = el.getAttribute('aria-label');
+    if (aria) push('aria', '[aria-label="' + attrValue(aria) + '"]', 'css');
+    const role = el.getAttribute('role');
+    if (role) push('role', tag + '[role="' + attrValue(role) + '"]', 'css');
+    for (const cls of el.classList) {  // a single class that is unique is a decent, readable hook
+      const s = '.' + CSS.escape(cls);
+      if (isUnique(s)) { out.push({ strategy: 'class', selector: s, selector_type: 'css', unique: true }); break; }
+    }
+
+    if (el.matches(CLICKABLE) || role === 'button') {
+      const text = visibleText(el);
+      if (text) {
+        // Uniqueness must match get_by_text at run time: substring, case-insensitive, whole DOM.
+        // Count the *deepest* elements containing the text (no child also contains it), which
+        // approximates get_by_text's leaf matching. A brittle "License"-style text stays non-unique.
+        const norm = (s) => (s || '').trim().replace(/\s+/g, ' ').toLowerCase();
+        const needle = norm(text);
+        const hits = [...document.querySelectorAll('*')].filter((e) =>
+          norm(e.textContent).includes(needle) &&
+          ![...e.children].some((c) => norm(c.textContent).includes(needle)));
+        out.push({ strategy: 'text', selector: text, selector_type: 'text', unique: hits.length === 1 });
+      }
+    }
+    return out;
+  };
+
+  const descriptorFor = (el) => ({
+    tag: el.tagName.toLowerCase(),
+    css_path: cssPath(el),
+    text: visibleText(el),
+    name: el.getAttribute('name'),
+    field_type: (el.getAttribute('type') || '').toLowerCase() || null,
+    autocomplete: el.getAttribute('autocomplete'),
+    candidates: candidates(el),
+  });
+
+  // A selector matching `el` AND its repeating siblings (for lists/records: the shared class that
+  // yields the most matches, else the tag). Distinct from candidates(), which seek a *unique* hook.
+  const groupSelector = (el) => {
+    let best = null, bestCount = 1;
+    for (const cls of el.classList) {
+      const s = '.' + CSS.escape(cls);
+      const n = isUnique(s) ? 1 : (() => { try { return document.querySelectorAll(s).length; } catch (e) { return 0; } })();
+      if (n >= 2 && n > bestCount) { best = s; bestCount = n; }
+    }
+    if (best) return best;
+    const tag = el.tagName.toLowerCase();
+    return tag;
+  };
+
+  // A selector for `el` scoped *within* `container` (for records: `.title` inside `.product`).
+  const relativeSelector = (container, el) => {
+    const testId = testIdAttr(el);
+    if (testId) {
+      const s = '[' + testId[0] + '="' + attrValue(testId[1]) + '"]';
+      if (isUnique(s, container)) return s;
+    }
+    for (const cls of el.classList) {
+      const s = '.' + CSS.escape(cls);
+      if (isUnique(s, container)) return s;
+    }
+    const tag = el.tagName.toLowerCase();
+    if (isUnique(tag, container)) return tag;
+    // Fallback: nth-of-type path from just under the container down to el.
+    const parts = [];
+    let node = el;
+    while (node && node !== container && node.parentElement) {
+      let part = node.tagName.toLowerCase();
+      const sameTag = [...node.parentElement.children].filter((c) => c.tagName === node.tagName);
+      if (sameTag.length > 1) part += ':nth-of-type(' + (sameTag.indexOf(node) + 1) + ')';
+      parts.unshift(part);
+      node = node.parentElement;
+    }
+    return parts.join(' > ') || tag;
+  };
+
+  window.__aeSel = { CLICKABLE, isUnique, cssPath, visibleText, candidates, descriptorFor,
+                     groupSelector, relativeSelector };
+})();
+"""

aetherius/recorder/_transform.py

@@ -0,0 +1,214 @@
+"""Pure transformation of captured events into Blueprint steps, inputs, secrets and outputs.
+
+No browser here: this is the testable heart of the recorder. Actions become navigate/click/fill/
+select/press steps; overlay picks become a single coalesced ``extract`` step (single values, lists or
+record tables) plus the Blueprint ``outputs`` map; ``wait_for`` and ``parameterize`` (turn a filled
+value into an ``input``) round out the "beyond clicks" meta-actions.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._names import ident as _ident
+from ._names import unique as _unique
+from .capture import RecordedEvent
+from .selector_synth import ElementDescriptor, SelectorChoice, synthesize
+
+_CREDENTIAL_TOKENS = ("username", "user", "login", "email", "mail", "pass", "identifiant", "pseudo")
+_CREDENTIAL_AUTOCOMPLETE = {"username", "email", "current-password", "new-password"}
+# A navigation right after one of these was triggered by it, not typed by hand.
+_NAV_TRIGGERS = frozenset({"click", "press"})
+_ELEMENT_KINDS = frozenset({"click", "fill", "select", "press"})
+_EXTRACT_KINDS = frozenset({"extract", "extract_records"})
+
+
+def _selector_fields(choice: SelectorChoice) -> dict[str, str]:
+    """Selector fields for a step: ``selector_type`` omitted when it is the ``css`` default."""
+    fields = {"selector": choice.selector}
+    if choice.selector_type != "css":
+        fields["selector_type"] = choice.selector_type
+    return fields
+
+
+def _is_credential(descriptor: ElementDescriptor | None) -> bool:
+    """True when a text field looks like a credential worth turning into a secret."""
+    if descriptor is None:
+        return False
+    if (descriptor.field_type or "") == "password":
+        return True
+    if (descriptor.autocomplete or "").lower() in _CREDENTIAL_AUTOCOMPLETE:
+        return True
+    haystack = f"{descriptor.name or ''} {descriptor.autocomplete or ''}".lower()
+    return any(token in haystack for token in _CREDENTIAL_TOKENS)
+
+
+def _choice(descriptor: ElementDescriptor | None) -> SelectorChoice:
+    return synthesize(descriptor) if descriptor is not None else SelectorChoice("")
+
+
+class _Recording:
+    """Accumulates the Blueprint pieces as captured events are handled, in order."""
+
+    def __init__(self, *, credentials_as_secrets: bool) -> None:
+        self.credentials_as_secrets = credentials_as_secrets
+        self.steps: list[dict[str, Any]] = []
+        self.secrets: list[str] = []
+        self.inputs: dict[str, Any] = {}
+        self.outputs: dict[str, Any] = {}
+        self._secret_by_selector: dict[str, str] = {}
+        self._extract: dict[str, Any] | None = None  # current open extract step
+        self._extract_id: str = ""
+        self._extract_seq = 0
+        self._output_names: set[str] = set()
+        self._prev_kind: str | None = None
+
+    def handle(self, event: RecordedEvent) -> None:
+        kind = event.kind
+        if kind in _EXTRACT_KINDS:
+            self._add_extraction(event)
+        else:
+            self._extract = None  # any non-extraction closes the coalesced extract step
+            if kind == "navigate":
+                self._add_navigate(event)
+            elif kind == "wait_for":
+                self._add_wait_for(event)
+            elif kind == "parameterize":
+                self._parameterize(event)
+            elif kind in _ELEMENT_KINDS:
+                self._add_element(event)
+        self._prev_kind = kind
+
+    # ── actions ──────────────────────────────────────────────────────────────
+    def _add_navigate(self, event: RecordedEvent) -> None:
+        if self._prev_kind not in _NAV_TRIGGERS and event.url:
+            self.steps.append({"action": "navigate", "url": event.url})
+
+    def _add_wait_for(self, event: RecordedEvent) -> None:
+        choice = _choice(event.descriptor)
+        config = event.config or {}
+        # Presence check: a group class beats a positional path when there is no unique hook.
+        if choice.strategy == "css_path" and config.get("group"):
+            fields: dict[str, str] = {"selector": str(config["group"])}
+        else:
+            fields = _selector_fields(choice)
+        self.steps.append({"action": "wait_for", **fields})
+
+    def _add_element(self, event: RecordedEvent) -> None:
+        choice = _choice(event.descriptor)
+        selector_fields = _selector_fields(choice)
+        if event.kind == "click":
+            if event.url:  # a link click: navigate to its (stable) URL rather than replay the click
+                self.steps.append({"action": "navigate", "url": event.url})
+            else:
+                self.steps.append({"action": "click", **selector_fields})
+        elif event.kind == "press":
+            self.steps.append({"action": "press", "key": event.key or "Enter", **selector_fields})
+        elif event.kind == "select":
+            self.steps.append({"action": "select", **selector_fields, "value": event.value or ""})
+        elif event.kind == "fill":
+            self._add_fill(event, choice, selector_fields)
+
+    def _add_fill(
+        self, event: RecordedEvent, choice: SelectorChoice, selector_fields: dict[str, str]
+    ) -> None:
+        secret = event.redacted or (
+            self.credentials_as_secrets and _is_credential(event.descriptor)
+        )
+        if secret:
+            value = f"{{{{ secrets.{self._secret_for(event, choice)} }}}}"
+        else:
+            value = event.value or ""
+        step = {"action": "fill", **selector_fields, "value": value}
+        last = self.steps[-1] if self.steps else None
+        if (
+            last is not None
+            and last.get("action") == "fill"
+            and last.get("selector") == choice.selector
+        ):
+            self.steps[-1] = step  # coalesce successive edits of the same field
+        else:
+            self.steps.append(step)
+
+    def _secret_for(self, event: RecordedEvent, choice: SelectorChoice) -> str:
+        name = self._secret_by_selector.get(choice.selector)
+        if name is None:
+            base = _ident(event.descriptor.name if event.descriptor else None, fallback="secret")
+            name = _unique(base, set(self.secrets))
+            self._secret_by_selector[choice.selector] = name
+            self.secrets.append(name)
+        return name
+
+    def _parameterize(self, event: RecordedEvent) -> None:
+        """Rewrite the most recent literal fill at this selector into an ``{{ inputs.x }}``."""
+        selector = _choice(event.descriptor).selector
+        for step in reversed(self.steps):
+            if step.get("action") == "fill" and step.get("selector") == selector:
+                if str(step.get("value", "")).startswith("{{ secrets."):
+                    return  # a secret is not an input; leave it alone
+                name = _unique(
+                    _ident((event.config or {}).get("name"), fallback="value"), set(self.inputs)
+                )
+                step["value"] = f"{{{{ inputs.{name} }}}}"
+                self.inputs[name] = {"type": "string", "required": True}
+                return
+
+    # ── extraction ───────────────────────────────────────────────────────────
+    def _add_extraction(self, event: RecordedEvent) -> None:
+        if self._extract is None:
+            self._extract_seq += 1
+            self._extract_id = "data" if self._extract_seq == 1 else f"data_{self._extract_seq}"
+            self._extract = {"action": "extract", "id": self._extract_id, "outputs": {}}
+            self.steps.append(self._extract)
+        config = event.config or {}
+        name = _unique(_ident(config.get("name"), fallback="value"), self._output_names)
+        self._output_names.add(name)
+        self._extract["outputs"][name] = self._spec(event, config)
+        self.outputs[name] = f"{{{{ steps.{self._extract_id}.{name} }}}}"
+
+    def _spec(self, event: RecordedEvent, config: dict[str, Any]) -> dict[str, Any]:
+        if event.kind == "extract_records":
+            return self._records_spec(event, config)
+        as_ = str(config.get("as", "text"))
+        # list/count read *all* matches, so use the sibling-group selector; single values use the
+        # unique selector our policy synthesizes from the descriptor.
+        if as_ in ("list", "count") and config.get("group"):
+            spec: dict[str, Any] = {"selector": str(config["group"])}
+        else:
+            spec = dict(_selector_fields(_choice(event.descriptor)))
+        spec["as"] = as_
+        if as_ == "list":
+            item = str(config.get("item") or "text")
+            if item != "text":
+                spec["item"] = item
+            if item == "attr" and config.get("attr"):
+                spec["attr"] = str(config["attr"])
+        elif as_ == "attr" and config.get("attr"):
+            spec["attr"] = str(config["attr"])
+        return spec
+
+    def _records_spec(self, event: RecordedEvent, config: dict[str, Any]) -> dict[str, Any]:
+        fields: dict[str, Any] = {}
+        taken: set[str] = set()
+        for raw in config.get("fields", []):
+            fname = _unique(_ident(raw.get("name"), fallback="field"), taken)
+            taken.add(fname)
+            field_spec = {
+                "selector": str(raw.get("selector", "")),
+                "as": str(raw.get("as", "text")),
+            }
+            if raw.get("as") == "attr" and raw.get("attr"):
+                field_spec["attr"] = str(raw["attr"])
+            fields[fname] = field_spec
+        each = str(config.get("each") or _choice(event.descriptor).selector)
+        return {"each": each, "fields": fields}
+
+
+def events_to_steps(
+    events: list[RecordedEvent], *, credentials_as_secrets: bool = True
+) -> tuple[list[dict[str, Any]], list[str], dict[str, Any], dict[str, Any]]:
+    """Transform captured events into ``(steps, secrets, inputs, outputs)``."""
+    recording = _Recording(credentials_as_secrets=credentials_as_secrets)
+    for event in events:
+        recording.handle(event)
+    return recording.steps, recording.secrets, recording.inputs, recording.outputs