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 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({ trace: cfg.trace, mode: cfg.mode, autoplay: false, controls: false, resumeKey: cfg.key, ...cfg.rate ? { rate: cfg.rate } : {}, ...cfg.captions ? { captions: cfg.captions } : {} });
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) => send({ type: "stalled", index: e.index, reason: e.reason }));
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 !== "not-found") return { why: `the step ${stall.reason === "until-timeout" ? "waited for a text that never appeared" : "timed out waiting"}; only a missing element can be repaired`, top: [] };
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 sg = repairSuggestion(current, s.index, found.chosen.target, found.chosen.why ? { why: found.chosen.why } : {});
1086
- out.suggestions.push({ ...sg, id: out.suggestions.length + 1, by: found.chosen.by, ...found.chosen.score !== void 0 ? { score: found.chosen.score } : {} });
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-BM26YQ4L.js.map
1777
+ //# sourceMappingURL=chunk-VTXIXGG4.js.map