trace-avatar-render 0.1.0 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +23 -0
- package/README.md +11 -1
- package/dist/{chunk-BM26YQ4L.js → chunk-VTXIXGG4.js} +58 -10
- package/dist/chunk-VTXIXGG4.js.map +1 -0
- package/dist/cli.js +65 -8
- package/dist/cli.js.map +1 -1
- package/dist/index.d.ts +33 -7
- package/dist/index.js +1 -1
- package/package.json +2 -2
- package/dist/chunk-BM26YQ4L.js.map +0 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,28 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.1.2 (10 Nov 2026)
|
|
4
|
+
|
|
5
|
+
- `--navigate` (`navigate: true` in `render()`): when a step is on another page, the renderer loads that page, as the
|
|
6
|
+
app's router would (the player's `navigate`), and the guide carries on there. Without it, a Show me guide that
|
|
7
|
+
crosses pages (Show me never clicks) waited on "Open … to continue" until the render timed out. Found rendering
|
|
8
|
+
DutyCaptain's guides for traceavatar.com, and needed by its nightly guide checks.
|
|
9
|
+
- `--security [guards]` and `--value name=text` (`security`, `values` in `render()`): Do it for me's security and
|
|
10
|
+
run-time values, passed to the player (trace-avatar 0.1.14 or later). An upload hand-off no longer writes into the
|
|
11
|
+
step's element.
|
|
12
|
+
- trace-avatar ^0.1.13: 0.1.9 typed the first letter of a rich-text field (Lexical) away ("ind the opening hours").
|
|
13
|
+
|
|
14
|
+
## 0.1.1 (10 Nov 2026)
|
|
15
|
+
|
|
16
|
+
- `--report <file>` writes one guide's outcome as JSON, whatever the exit code: `{ outcome: 'passed' | 'stalled' |
|
|
17
|
+
'failed', step, reason, message }`. A stall names its step (from 0), why (`not-found` or `until-timeout`) and
|
|
18
|
+
that step's caption, plus `repair` when `--repair` wrote `<out>.repair.json`. For CI jobs that check many guides
|
|
19
|
+
and keep the results (DutyCaptain's guide checks).
|
|
20
|
+
|
|
21
|
+
- `--repair` fixes a wait whose text changed (`until-timeout`): the texts where it looks and those that showed while
|
|
22
|
+
it waited are scored (code first, `--ai` only when unsure); a fix of `kind: 'until'` goes to `<out>.repair.json`,
|
|
23
|
+
verified by playing again. With no clear winner, a guess (`by: 'guess'`) is offered and kept only when the replay
|
|
24
|
+
passes. `--hide` and `--blur` areas are never offered. Needs trace-avatar 0.1.9 or later.
|
|
25
|
+
|
|
3
26
|
## 0.1.0 (first release)
|
|
4
27
|
|
|
5
28
|
- Render a trace-avatar guide to a **GIF** or an **MP4** by playing it on your real app in headless Chromium, in
|
package/README.md
CHANGED
|
@@ -43,6 +43,9 @@ Because the guide is known before it plays, the render can do what a screen reco
|
|
|
43
43
|
| `--hide <selector>` | hidden before capture (your dev toolbars); repeatable |
|
|
44
44
|
| `--blur <selector>` | blurred before capture, as well as `[data-trace-blur]` in your app; repeatable |
|
|
45
45
|
| `--allow-stall` | render a stalled guide instead of failing |
|
|
46
|
+
| `--navigate` | when a step is on another page, load that page as your app's router would. Without it, a Show me guide that crosses pages waits on "Open … to continue" |
|
|
47
|
+
| `--security [guards]` | Do it for me: leave these to the viewer, as trace-avatar's `security`: `all`, or `secrets,money,files`. A hand-off is held for a beat, then the guide plays on |
|
|
48
|
+
| `--value name=text` | Do it for me: a value to type, by name or field label (`password=demo-pass`), as trace-avatar's `values`; repeatable. A password field still shows bullets |
|
|
46
49
|
| `--player <file>` | the `trace-perform.min.js` to use (default: the installed trace-avatar; or set `TRACE_AVATAR_PLAYER`) |
|
|
47
50
|
| `--timeline <file>` | write the player's events and the cuts as JSON |
|
|
48
51
|
| `--timeout <ms>` | give up after this long (default 120000) |
|
|
@@ -94,7 +97,14 @@ frames are sent only with `--qa`.
|
|
|
94
97
|
what the step means, and re-records that element as the step's target. Code scores the candidates first; an AI
|
|
95
98
|
is asked only when unsure (with `--ai`, DeepSeek first; `--repair-vision` adds a screenshot). Each fix is verified by
|
|
96
99
|
playing the guide again, up to 5 stalls in one run. The fixes go to `<out>.repair.json` with
|
|
97
|
-
`verified`, how each was chosen and, for an unresolved step, the best 3 candidates. The render still exits 1
|
|
100
|
+
`verified`, how each was chosen and, for an unresolved step, the best 3 candidates. The render still exits 1.
|
|
101
|
+
|
|
102
|
+
A wait whose text never showed (`until-timeout`: it waited for "Saved", the app now says "Changes stored") is
|
|
103
|
+
repaired the same way, with a fix of `kind: 'until'`. The candidates are the short texts where the wait looks, plus
|
|
104
|
+
those that showed while it waited (a message that came and went counts). When no text is a clear winner and no AI
|
|
105
|
+
settles it, the best one that scores well, else what the app showed after the action, is offered as
|
|
106
|
+
`by: 'guess'`; it is kept only when playing the guide again gets past the wait. `--hide` and `--blur` areas are
|
|
107
|
+
never offered:
|
|
98
108
|
|
|
99
109
|
```sh
|
|
100
110
|
trace-avatar-render invoice.trace.json --url … --out invoice.gif --repair --ai gateway
|
|
@@ -115,7 +115,21 @@ function bootstrap(cfg) {
|
|
|
115
115
|
style.textContent = (cfg.hide.length ? `${cfg.hide.join(",")}{visibility:hidden!important}
|
|
116
116
|
` : "") + `${["[data-trace-blur]", ...cfg.blur].join(",")}{filter:blur(8px)!important}`;
|
|
117
117
|
(document.head || document.documentElement).append(style);
|
|
118
|
-
c = w.__taPlayer.createTrace({
|
|
118
|
+
c = w.__taPlayer.createTrace({
|
|
119
|
+
trace: cfg.trace,
|
|
120
|
+
mode: cfg.mode,
|
|
121
|
+
autoplay: false,
|
|
122
|
+
controls: false,
|
|
123
|
+
resumeKey: cfg.key,
|
|
124
|
+
...cfg.rate ? { rate: cfg.rate } : {},
|
|
125
|
+
...cfg.captions ? { captions: cfg.captions } : {},
|
|
126
|
+
// A step on another page: go there, as an app's router would (the player carries on after the load).
|
|
127
|
+
...cfg.navigate ? { navigate: (path) => {
|
|
128
|
+
location.assign(path);
|
|
129
|
+
} } : {},
|
|
130
|
+
...cfg.security !== void 0 ? { security: cfg.security } : {},
|
|
131
|
+
...cfg.values ? { values: cfg.values } : {}
|
|
132
|
+
});
|
|
119
133
|
w.__taRender = c;
|
|
120
134
|
c.on("state", ({ phase }) => {
|
|
121
135
|
send({ type: "state", phase });
|
|
@@ -133,13 +147,16 @@ function bootstrap(cfg) {
|
|
|
133
147
|
...typeof e.step.say === "string" && e.step.say.trim() ? { say: e.step.say } : {}
|
|
134
148
|
});
|
|
135
149
|
});
|
|
136
|
-
c.on("stalled", (e) =>
|
|
150
|
+
c.on("stalled", (e) => {
|
|
151
|
+
window.__taSeen = e.seen ?? [];
|
|
152
|
+
send({ type: "stalled", index: e.index, reason: e.reason });
|
|
153
|
+
});
|
|
137
154
|
c.on("page", (e) => send({ type: "page", index: e.index }));
|
|
138
155
|
c.on("blocked", (e) => send({ type: "blocked", message: e.say }));
|
|
139
156
|
c.on("handoff", (e) => {
|
|
140
157
|
send({ type: "handoff", index: e.index });
|
|
141
158
|
const el = e.element;
|
|
142
|
-
if (el && "value" in el) {
|
|
159
|
+
if (e.step.type === "type" && el && "value" in el) {
|
|
143
160
|
el.focus();
|
|
144
161
|
el.value = e.step.text ?? "";
|
|
145
162
|
el.dispatchEvent(new Event("input", { bubbles: true }));
|
|
@@ -170,7 +187,10 @@ async function capture(o) {
|
|
|
170
187
|
blur: o.blur ?? [],
|
|
171
188
|
...o.rate ? { rate: o.rate } : {},
|
|
172
189
|
pauseHoldMs: o.pauseHoldMs ?? 1200,
|
|
173
|
-
...o.captions ? { captions: o.captions } : {}
|
|
190
|
+
...o.captions ? { captions: o.captions } : {},
|
|
191
|
+
...o.navigate ? { navigate: true } : {},
|
|
192
|
+
...o.security !== void 0 ? { security: o.security } : {},
|
|
193
|
+
...o.values ? { values: o.values } : {}
|
|
174
194
|
};
|
|
175
195
|
const content = `${readFileSync(o.playerFile, "utf8")}
|
|
176
196
|
;window.__taPlayer = TraceAvatar;
|
|
@@ -1013,7 +1033,7 @@ async function suggestScript(ai, trace) {
|
|
|
1013
1033
|
// src/repair.ts
|
|
1014
1034
|
import { existsSync, readFileSync as readFileSync2 } from "fs";
|
|
1015
1035
|
import { dirname, join } from "path";
|
|
1016
|
-
import { applyRaw, chooseRepair, repairSuggestion } from "trace-avatar/assist";
|
|
1036
|
+
import { applyRaw, chooseRepair, chooseWait, guessWait, repairSuggestion, typedOf, waitSuggestion } from "trace-avatar/assist";
|
|
1017
1037
|
function repairScriptOf(playerFile) {
|
|
1018
1038
|
const file = join(dirname(playerFile), "trace-repair.min.js");
|
|
1019
1039
|
if (!existsSync(file)) throw new RenderError(`--repair needs trace-avatar 0.1.7 or later (no ${file})`);
|
|
@@ -1023,7 +1043,8 @@ function stallInspector(o) {
|
|
|
1023
1043
|
const code = `${readFileSync2(o.script, "utf8")}
|
|
1024
1044
|
;window.__taRepair = TraceAvatarRepair;`;
|
|
1025
1045
|
return async (page, stall) => {
|
|
1026
|
-
if (stall.reason
|
|
1046
|
+
if (stall.reason === "until-timeout") return waitInspect(page, stall.index);
|
|
1047
|
+
if (stall.reason !== "not-found") return { why: "the step timed out waiting; only a missing element or a changed text can be repaired", top: [] };
|
|
1027
1048
|
await page.evaluate(code);
|
|
1028
1049
|
const skip = o.skip?.length ? o.skip.join(", ") : void 0;
|
|
1029
1050
|
const list = await page.evaluate((sk) => window.__taRepair.candidatesOf(document, sk ? { skip: sk } : {}), skip);
|
|
@@ -1043,6 +1064,29 @@ function stallInspector(o) {
|
|
|
1043
1064
|
if (!r.ok) return { why: "the chosen element could not be told apart from others on the page", top };
|
|
1044
1065
|
return { chosen: { target: r.target, by: choice.by, ...choice.score !== void 0 ? { score: choice.score } : {}, ...choice.why ? { why: choice.why } : {} }, top };
|
|
1045
1066
|
};
|
|
1067
|
+
async function waitInspect(page, index) {
|
|
1068
|
+
await page.evaluate(code);
|
|
1069
|
+
if (!await page.evaluate(() => typeof window.__taRepair.textsOf === "function")) {
|
|
1070
|
+
return { why: "repairing a wait needs trace-avatar 0.1.9 or later", top: [] };
|
|
1071
|
+
}
|
|
1072
|
+
const trace = o.trace();
|
|
1073
|
+
const list = await page.evaluate(({ target, typed, skip }) => {
|
|
1074
|
+
const w = window;
|
|
1075
|
+
const r = w.__taRepair;
|
|
1076
|
+
const out = (el) => !!skip && !!el?.closest(skip);
|
|
1077
|
+
const seen = (w.__taSeen ?? []).filter((x) => !out(x.element));
|
|
1078
|
+
return r.textsOf(r.scopeFor(target ?? void 0, document), { seen, typed }).filter((c) => !out(r.elementOf(c.id))).map((c, id) => ({ ...c, id }));
|
|
1079
|
+
}, { target: trace.steps[index]?.target ?? null, typed: typedOf(trace), skip: o.skip?.length ? o.skip.join(", ") : "" });
|
|
1080
|
+
const choice = await chooseWait(trace, index, list, o.ai ? { ai: o.ai } : {});
|
|
1081
|
+
const top = choice.top.map((t) => {
|
|
1082
|
+
const { id: _i, ...c } = list[t.id];
|
|
1083
|
+
return { ...c, score: t.score };
|
|
1084
|
+
});
|
|
1085
|
+
const best = guessWait(choice, list);
|
|
1086
|
+
if (!best) return { why: choice.why ?? (o.ai ? "no text on the page fits the wait" : "no clear match; pass --ai to ask, or pick one"), top };
|
|
1087
|
+
const score = choice.top.find((t) => t.id === best.id)?.score;
|
|
1088
|
+
return { text: { value: best.text, by: best.guess ? "guess" : choice.by, ...score !== void 0 ? { score } : {}, ...choice.why && !best.guess ? { why: choice.why } : {} }, top };
|
|
1089
|
+
}
|
|
1046
1090
|
}
|
|
1047
1091
|
async function repairGuide(o) {
|
|
1048
1092
|
let current = o.trace;
|
|
@@ -1074,7 +1118,7 @@ async function repairGuide(o) {
|
|
|
1074
1118
|
}
|
|
1075
1119
|
}
|
|
1076
1120
|
const found = s.data;
|
|
1077
|
-
if (!found?.chosen) {
|
|
1121
|
+
if (!found?.chosen && !found?.text) {
|
|
1078
1122
|
out.unresolved.push({ index: s.index, reason: s.reason, why: found?.why ?? "the page could not be looked at", top: found?.top ?? [] });
|
|
1079
1123
|
return out;
|
|
1080
1124
|
}
|
|
@@ -1082,8 +1126,9 @@ async function repairGuide(o) {
|
|
|
1082
1126
|
out.unresolved.push({ index: s.index, reason: s.reason, why: `stopped after ${o.maxStalls ?? 5} repairs`, top: found.top });
|
|
1083
1127
|
return out;
|
|
1084
1128
|
}
|
|
1085
|
-
const
|
|
1086
|
-
|
|
1129
|
+
const pick = found.chosen ?? found.text;
|
|
1130
|
+
const sg = found.chosen ? repairSuggestion(current, s.index, found.chosen.target, pick.why ? { why: pick.why } : {}) : waitSuggestion(current, s.index, found.text.value, pick.why ? { why: pick.why } : {});
|
|
1131
|
+
out.suggestions.push({ ...sg, id: out.suggestions.length + 1, by: pick.by, ...pick.score !== void 0 ? { score: pick.score } : {} });
|
|
1087
1132
|
current = applyRaw(current, [sg]);
|
|
1088
1133
|
}
|
|
1089
1134
|
return out;
|
|
@@ -1230,6 +1275,9 @@ async function render(o) {
|
|
|
1230
1275
|
timeoutMs: o.timeoutMs,
|
|
1231
1276
|
headless: o.headless,
|
|
1232
1277
|
leadMs: LEAD_MS,
|
|
1278
|
+
...o.navigate ? { navigate: true } : {},
|
|
1279
|
+
...o.security !== void 0 ? { security: o.security } : {},
|
|
1280
|
+
...o.values ? { values: o.values } : {},
|
|
1233
1281
|
...burn ? { captions: "none" } : {}
|
|
1234
1282
|
};
|
|
1235
1283
|
if (o.repair) repairScriptOf(capOpts.playerFile);
|
|
@@ -1726,4 +1774,4 @@ export {
|
|
|
1726
1774
|
cached,
|
|
1727
1775
|
voiceOf
|
|
1728
1776
|
};
|
|
1729
|
-
//# sourceMappingURL=chunk-
|
|
1777
|
+
//# sourceMappingURL=chunk-VTXIXGG4.js.map
|