Skip to content

A local video studio for your coding agent. Describe a video in one sentence: your agent directs, your machine renders. Claude Code, Codex, Cursor, Devin and more. No API keys, no uploads.

showtime 0.4.6: a stuck page's check error names the first late seek and lists the last seeks; its --json report reaches adopt and render whole

Favio Vázquez13c0b64cd58a
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e140f00..e564b62 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -95,7 +95,11 @@ it.
did) cost a minute per step, half an hour for a 3 s film, and check could wait with no end. Now a seek past its
deadline asks the page for a quick answer: no answer, or a second late seek in a row, ends check with an error
naming the seek and its last step, with a hint that points at the page's own code, and the browser closes with it.
- The dense timeline's other page reads, and the samples' text reads, wait under the same deadline.
+ The dense timeline's other page reads, and the samples' text reads, wait under the same deadline. The error names
+ the first seek that ran late, where the page got stuck (the seeks after it wait behind it), counts the seeks that
+ failed in another way just before, and lists the last six seeks with how long each took; with `--json` the output is
+ a report holding one `page_stuck` error and those seeks (`adopt` counts it as an error; `render --size` notes that
+ check stopped early and goes on).
- **Fixed: `export html --interactive` packs a page's own fonts** (#71). The X-ray live page and the living diagram's
figure packed the files of linked stylesheets only; a project's own `@font-face` in the page's `<style>`
(`url("fonts/x.woff2")`) stayed a file the page's policy (`font-src data:`) blocks, so the text fell back to another
diff --git a/skills/showtime/references/render.md b/skills/showtime/references/render.md
index 7d33267..1599f00 100644
--- a/skills/showtime/references/render.md
+++ b/skills/showtime/references/render.md
@@ -49,13 +49,13 @@ slow, fails, or looks different from the preview; or when you need the exact fla
|---|---|
| The loop | 60-138 |
| showtime render <project> | 140-281 |
-| showtime check <project> | 283-343 |
-| showtime snap <project / video> | 345-366 |
-| showtime preview <project> | 368-385 |
-| showtime retime <project> -d <seconds> | 387-442 |
-| Speed | 444-547 |
-| Troubleshooting | 549-563 |
-| Platforms | 565-580 |
+| showtime check <project> | 283-344 |
+| showtime snap <project / video> | 346-367 |
+| showtime preview <project> | 369-386 |
+| showtime retime <project> -d <seconds> | 388-443 |
+| Speed | 445-548 |
+| Troubleshooting | 550-564 |
+| Platforms | 566-581 |
## The loop
@@ -288,6 +288,7 @@ exactly like the renderer and reports findings with the time they happen and a f
| Code | Severity | Means |
|---|---|---|
| `ready_failed`, `page_error`, `seek_error` | error | the page throws, or never becomes ready |
+| `page_stuck` | error | the page stopped answering, or its seeks stopped finishing (the first late seek is named): check ends there, and `--json` gets this one finding |
| `network`, `missing_file` | error | remote request (blocked in renders) or 404 |
| `request_failed` | warning | a local request failed (not a 404). A load cancelled while it ran (an image whose `src` changed again before it arrived, as when check's seeks swap pictures) is not a failure: report.json `cancelled_loads` counts those |
| `unstable_frame` | error | pixels keep changing after a seek finished: something runs on real time |
diff --git a/skills/showtime/scripts/adopt.mjs b/skills/showtime/scripts/adopt.mjs
index c89dbe1..8cb6377 100644
--- a/skills/showtime/scripts/adopt.mjs
+++ b/skills/showtime/scripts/adopt.mjs
@@ -1106,7 +1106,9 @@ async function runCheck(dest) {
const sev = (x) => x.severity || x.level;
return {
exit: r.code, errors: items.filter((x) => sev(x) === 'error').length, warnings: items.filter((x) => sev(x) === 'warning').length,
- report: j.report || path.join(dest, 'work', 'check', 'report.json'), sheet: j.sheet || path.join(dest, 'work', 'check', 'sheet.jpg'),
+ // a check that stopped (its report says why in `error`) wrote no report or sheet: name none
+ report: j.report || (j.error ? undefined : path.join(dest, 'work', 'check', 'report.json')),
+ sheet: j.sheet || (j.error ? undefined : path.join(dest, 'work', 'check', 'sheet.jpg')),
// one line per code (a typed terminal line is hundreds of short_text notes): count + the first one
top: groupFindings(items.filter((x) => sev(x) === 'error' || sev(x) === 'warning')).slice(0, 6),
};
diff --git a/skills/showtime/scripts/check.mjs b/skills/showtime/scripts/check.mjs
index a223795..29fbcd7 100644
--- a/skills/showtime/scripts/check.mjs
+++ b/skills/showtime/scripts/check.mjs
@@ -329,10 +329,32 @@ async function main() {
// check naming the step. Before, a seek past its deadline only skipped the step, so a stuck page cost 60 s x pace
// per step of the timeline (31 steps for a 3 s film), longer than any caller waits (macOS CI runners).
let seekLate = 0; // seeks past their deadline in a row, on a page that still answers
+ let lateFirst = null; // the first of them, where the page got stuck (later seeks wait behind it): { t, s, i }
+ const seekOther = { n: 0, first: '' }; // seeks that failed without a deadline since the last one that worked
+ const seekTrail = []; // the last 6 seeks: { t, outcome: 'ok' | 'late' | 'error', ms }
+ let seekN = 0;
+ // tests only: SHOWTIME_TEST_CHECK_STUCK=1 fails every seek at its deadline (the page itself answers), so the tests of
+ // check's callers reach this ending without a stuck page; =pad:N adds N bytes to its --json report (a large report)
+ const TEST_STUCK = /^(1|pad:(\d+))$/.exec(process.env.SHOWTIME_TEST_CHECK_STUCK || '');
const PAGE_STUCK_HINT = 'the page\'s own code may be stuck there (its ST.onSeek handler or a script it runs at that time): open it with `showtime preview` and seek to that time; or the machine is too busy: close other heavy programs and retry';
+ /** End check on a stuck page: the last seeks go to stderr, then the error. With --json, stdout gets the report
+ * so far with one page_stuck finding, its counts and the seeks: render's layout check and adopt read them. */
+ const stuckEnd = async (message) => {
+ const trail = seekTrail.map((r) => `${r.t.toFixed(3)}s ${r.outcome} ${r.ms} ms`).join(', ');
+ if (trail) process.stderr.write(c.dim(` the last seeks: ${trail}\n`));
+ if (a.json) {
+ const json = JSON.stringify({ ...report, ok: false, error: message, seeks: seekTrail,
+ findings: [{ severity: 'error', code: 'page_stuck', message }], summary: { errors: 1, warnings: 0, infos: 0 },
+ ...(TEST_STUCK && TEST_STUCK[2] ? { test_pad: 'x'.repeat(Number(TEST_STUCK[2])) } : {}) }, null, 2) + '\n';
+ // failNow exits at once: a pipe takes the write in parts (64 KB), so the rest waits for this callback, for 10 s
+ // x pace at most (a reader that does not read never lets it come)
+ await withPacedTimeout(new Promise((resolve) => process.stdout.write(json, () => resolve())), 10000, 'writing the report', sess.pace).catch(() => {});
+ }
+ failNow(`${message}; check's last step: ${doing}`, PAGE_STUCK_HINT);
+ };
const pageStuck = async (what) => {
const alive = await withPacedTimeout(sess.page.evaluate(() => 1), 15000, 'answering a ping', sess.pace).then(() => true, () => false);
- if (!alive) failNow(`the page stopped answering: ${what}; check's last step: ${doing}`, PAGE_STUCK_HINT);
+ if (!alive) await stuckEnd(`the page stopped answering: ${what}`);
};
/** A page call on the timeline under the seek's deadline: past it, a page that does not answer ends check. */
const onPage = (p, what) => withPacedTimeout(p, 60000, what, sess.pace).catch(async (e) => {
@@ -341,12 +363,27 @@ async function main() {
return p; // slow, but the page answers: wait for it as before
});
const trySeek = async (x) => {
- try { await sess.seek(x); seekLate = 0; return true; } catch (e) {
+ const i = ++seekN, t1 = Date.now();
+ const note = (outcome) => { seekTrail.push({ t: x, outcome, ms: Date.now() - t1 }); if (seekTrail.length > 6) seekTrail.shift(); };
+ try {
+ if (TEST_STUCK) throw Object.assign(new Error(`timed out after 15s: seek to ${x.toFixed(3)}s`), { deadline: 'test' });
+ await sess.seek(x);
+ note('ok'); seekLate = 0; lateFirst = null; seekOther.n = 0;
+ return true;
+ } catch (e) {
const msg = String(e.message || e).replace(/^page\.evaluate: (Error: )?/, '').split('\n')[0];
+ note(e && e.deadline ? 'late' : 'error');
if (e && e.deadline) {
await pageStuck(msg);
- if (++seekLate >= 2) failNow(`the page's seeks stopped finishing: ${msg}, twice in a row; check's last step: ${doing}`, PAGE_STUCK_HINT);
- }
+ const late = { t: x, s: +((msg.match(/timed out after (\d+)s/) || [])[1] || 0), i };
+ if (++seekLate >= 2) {
+ const f = lateFirst;
+ const which = late.i === f.i + 1 ? `the seek to ${f.t.toFixed(3)}s and the one after it` : `the seeks to ${f.t.toFixed(3)}s and ${late.t.toFixed(3)}s`;
+ const other = seekOther.n ? ` (after ${seekOther.n} other seek error${seekOther.n > 1 ? 's' : ''}; the first: ${seekOther.first.slice(0, 160)})` : '';
+ await stuckEnd(`the page's seeks stopped finishing: ${which} timed out (${f.s === late.s ? `${f.s} s each` : `${f.s} s and ${late.s} s`})${other}`);
+ }
+ lateFirst = late;
+ } else if (!seekOther.n++) seekOther.first = msg;
const k = msg.split(' at t=')[0];
if (!seekErrors.has(k)) seekErrors.set(k, { t: x, msg });
return false;
diff --git a/skills/showtime/scripts/render.mjs b/skills/showtime/scripts/render.mjs
index b19ef36..291accc 100644
--- a/skills/showtime/scripts/render.mjs
+++ b/skills/showtime/scripts/render.mjs
@@ -196,6 +196,9 @@ async function main(retry = null) {
{ encoding: 'utf8', env: process.env, maxBuffer: 64 * 1024 * 1024 });
let rep = null;
try { rep = JSON.parse(r.stdout); } catch { rep = null; }
+ // check itself stopped (a page that stopped answering, a page that never got ready): say so, then render on
+ const stopped = /showtime check: error: ([^\n]*)/.exec(String(r.stderr || '').replace(/\x1b\[[0-9;]*m/g, ''));
+ if (stopped) { info(c.yellow(`showtime render: note: check stopped early: ${stopped[1]}; rendering on`)); logLine(`check stopped: ${stopped[1]}`); }
const LAYOUT = new Set(['text_clipped', 'text_off_canvas', 'safe_zone', 'text_overlap', 'overflow']);
const bad = rep ? rep.findings.filter((f) => f.severity === 'error' && f.code !== 'clip_timing' && (LAYOUT.has(f.code) || /clip|off_canvas|overflow/.test(f.code))) : [];
if (bad.length) {
diff --git a/skills/showtime/tests/test_adopt.py b/skills/showtime/tests/test_adopt.py
index c8d26fd..0458511 100644
--- a/skills/showtime/tests/test_adopt.py
+++ b/skills/showtime/tests/test_adopt.py
@@ -544,6 +544,23 @@ class Adopt(unittest.TestCase):
rep = json.loads((out / "adopt.json").read_text()) if (out / "adopt.json").exists() else None
return cp, out, rep
+ def test_a_check_that_ends_on_a_stuck_page_fails_the_adoption(self):
+ """check's --json on a stuck page is a report with one page_stuck finding (SHOWTIME_TEST_CHECK_STUCK fails every
+ seek at its deadline): adopt counts it as an error and exits non-zero."""
+ out = TMP / "stuck-check"
+ cp = subprocess.run([sys.executable, str(LAUNCHER), "adopt", str(FIX / "html-seek"), "-o", str(out)],
+ env=dict(ENV, SHOWTIME_TEST_CHECK_STUCK="1"), stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+ encoding="utf-8", errors="replace", timeout=900)
+ self.assertNotEqual(cp.returncode, 0, cp.stdout[-2000:])
+ rep = json.loads((out / "adopt.json").read_text())
+ self.assertFalse(rep["ok"])
+ self.assertGreaterEqual(rep["check"]["errors"], 1, rep["check"])
+ self.assertTrue(any("page_stuck" in t for t in rep["check"]["top"]), rep["check"])
+ # the stopped check wrote no sheet or report: none is named
+ self.assertIsNone(rep["check"].get("sheet"), rep["check"])
+ self.assertIsNone(rep["check"].get("report"), rep["check"])
+ self.assertNotIn("sheet:", cp.stdout + cp.stderr)
+
def test_html_seek(self):
cp, out, rep = self.adopt("html-seek")
self.assertEqual(rep["contract"], "page: seek(t)")
diff --git a/skills/showtime/tests/test_render.py b/skills/showtime/tests/test_render.py
index a4c33a2..57d3763 100644
--- a/skills/showtime/tests/test_render.py
+++ b/skills/showtime/tests/test_render.py
@@ -17,6 +17,7 @@ import _isolate # noqa: F401 (run from a scratch folder: never write into the
import array
import json
import os
+import re
import shutil
import struct
import subprocess
@@ -1125,29 +1126,94 @@ Film.start({ look: 'dark', design: [960, 540], fonts: ['600 1em "Inter Variable"
time.sleep(1)
return cp, took, procs
+ def test_13i_check_json_on_a_stuck_page_comes_whole_through_a_pipe(self):
+ """check --json on a stuck page ends with failNow's exit right after the report: a report over 64 KB still
+ arrives whole through a pipe (on macOS a pipe takes a write in parts; SHOWTIME_TEST_CHECK_STUCK=pad:N fails
+ every seek at its deadline and pads the report by N bytes)."""
+ proj = self.tmp / "stuck-json"
+ write(proj / "showtime.json", json.dumps({"width": 640, "height": 360, "fps": 30, "duration": 2}))
+ write(proj / "index.html", """<!doctype html><html><head><script src="/_st/stage.js"></script></head>
+<body style="margin:0;background:#0b0d12;color:#fff"><h1>Stuck page</h1></body></html>""")
+ cp = subprocess.run([sys.executable, str(LAUNCHER), "check", str(proj), "--json", "--no-determinism", "--samples", "2"],
+ env=dict(ENV, SHOWTIME_TEST_CHECK_STUCK="pad:300000"), stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+ encoding="utf-8", errors="replace", timeout=300)
+ self.assertEqual(cp.returncode, 1, cp.stderr[-2000:])
+ self.assertGreater(len(cp.stdout), 300000, "the report was cut at %d bytes" % len(cp.stdout))
+ report = json.loads(cp.stdout)
+ self.assertEqual(len(report["test_pad"]), 300000)
+ self.assertEqual([f["code"] for f in report["findings"]], ["page_stuck"])
+ self.assertIn("the page's seeks stopped finishing", report["error"])
+
+ @unittest.skipIf(os.name == "nt", "Node writes to pipes synchronously on Windows: a pipe nobody reads blocks the write")
+ def test_13j_check_on_a_stuck_page_ends_when_nobody_reads_its_report(self):
+ """check --json on a stuck page waits for its report to be written before it exits, for 10 s x pace at most: a
+ caller that never reads stdout (the pipe full after 64 KB) still sees check end, with its error, instead of a
+ check that waits for a reader with no end (SHOWTIME_TEST_CHECK_STUCK=pad:N pads the report past the pipe)."""
+ proj = self.tmp / "stuck-unread"
+ write(proj / "showtime.json", json.dumps({"width": 640, "height": 360, "fps": 30, "duration": 2}))
+ write(proj / "index.html", """<!doctype html><html><head><script src="/_st/stage.js"></script></head>
+<body style="margin:0;background:#0b0d12;color:#fff"><h1>Stuck page</h1></body></html>""")
+ err = self.tmp / "stuck-unread.err"
+ env = dict(ENV, SHOWTIME_TEST_CHECK_STUCK="pad:300000", SHOWTIME_TEST_WAIT_SCALE="0.25", SHOWTIME_TEST_OPEN_TIMEOUT="1200")
+ with open(err, "w") as ef:
+ p = subprocess.Popen([sys.executable, str(LAUNCHER), "check", str(proj), "--json", "--no-determinism", "--samples", "2"],
+ env=env, stdout=subprocess.PIPE, stderr=ef, start_new_session=True)
+ try:
+ rc = p.wait(timeout=120) # stdout is never read
+ except subprocess.TimeoutExpired:
+ os.killpg(p.pid, 9)
+ p.wait()
+ self.fail("check kept waiting for a reader of its report")
+ finally:
+ p.stdout.close()
+ self.assertEqual(rc, 1)
+ self.assertIn("the page's seeks stopped finishing", err.read_text(encoding="utf-8", errors="replace"))
+
def test_13h_check_ends_when_the_page_stops_answering(self):
"""A page that stops answering on the timeline ends check with an error naming where, instead of a check
that skips step after step at the seek's deadline each (31 steps for 3 s; macOS CI runners), and leaves no
browser behind: a seek that spins (between 1.25 s and 1.45 s, away from the samples: no answer to the probe),
- a seek that never finishes while the page still answers (two late seeks in a row), and a read on the
- timeline that spins (the step's canvas text)."""
+ a seek that never finishes while the page still answers (two late seeks in a row: the error names the first,
+ where the page got stuck, as the last seeks listed show it), the same after a seek that failed (counted), and
+ a read on the timeline that spins (the step's canvas text). The time and the browser are checked first, so a
+ message that changes never hides a browser left running."""
cases = (
("stuckseek", "ST.onSeek(function (t) { if (t >= 1.25 && t < 1.45) for (;;) {} });",
("the page stopped answering", "seek to 1.300s")),
("lateseek", "ST.onSeek(function (t) { if (t >= 1.25 && t < 1.45) return new Promise(function () {}); });",
- ("the page's seeks stopped finishing", "seek to 1.400s", "twice in a row")),
+ ("the page's seeks stopped finishing", "the last seeks: ")),
+ ("errseek", "ST.onSeek(function (t) { if (t >= 1.25 && t < 1.35) throw new Error('broken at ' + t);"
+ " if (t >= 1.35 && t < 1.55) return new Promise(function () {}); });",
+ ("the page's seeks stopped finishing", "the last seeks: ", "other seek error",
+ "the first: onSeek#2 at t=1.300: broken at 1.3)")),
("stuckread", "window.__stCanvasText = function () { for (;;) {} };",
("the page stopped answering", "reading the canvas text")),
)
for name, script, says in cases:
with self.subTest(name):
cp, took, procs = self.stuck_check(name, script)
+ self.assertEqual(procs, [], "the stuck page's browser was left running")
+ self.assertLess(took, 200, "check took %.0f s to give up on the stuck page" % took)
self.assertEqual(cp.returncode, 1, cp.stderr[-2000:])
for s in says:
self.assertIn(s, cp.stderr, cp.stderr[-2000:])
self.assertIn("showtime preview", cp.stderr, "the hint points at the page's own code")
- self.assertLess(took, 200, "check took %.0f s to give up on the stuck page" % took)
- self.assertEqual(procs, [], "the stuck page's browser was left running")
+ if name in ("lateseek", "errseek"):
+ # the first late seek is in the window (or after it: later seeks wait behind the stuck one) and
+ # is the first late one the listed seeks show after the last that worked
+ m = re.search(r"the seeks? to (\d+\.\d+)s and ", cp.stderr)
+ self.assertTrue(m, cp.stderr[-2000:])
+ self.assertGreaterEqual(float(m.group(1)), 1.3 if name == "lateseek" else 1.4, cp.stderr[-2000:])
+ trail = re.findall(r"(\d+\.\d+)s (ok|late|error) \d+ ms", cp.stderr.split("the last seeks: ")[1].split("\n")[0])
+ since = trail[max([i for i, r in enumerate(trail) if r[1] == "ok"] or [-1]) + 1:]
+ self.assertEqual(next(t for t, o in since if o == "late"), m.group(1), cp.stderr[-2000:])
+ if name == "lateseek":
+ report = json.loads(cp.stdout)
+ self.assertIs(report["ok"], False)
+ self.assertEqual([r["outcome"] for r in report["seeks"]][-2:], ["late", "late"], cp.stdout)
+ # a failed report its readers count (render's layout check and adopt read the findings)
+ self.assertEqual([(f["severity"], f["code"]) for f in report["findings"]], [("error", "page_stuck")])
+ self.assertEqual(report["summary"]["errors"], 1)
def test_14_check_judges_settled_frame_after_transition(self):
"""Text sliding through the vertical safe zone during a push transition is a note naming the
diff --git a/skills/showtime/tests/test_render_fixes.py b/skills/showtime/tests/test_render_fixes.py
index 8f4b77f..0bd56d6 100644
--- a/skills/showtime/tests/test_render_fixes.py
+++ b/skills/showtime/tests/test_render_fixes.py
@@ -337,6 +337,28 @@ class RenderSizeChecksItsPage(Tmp):
self.assertNotIn("the layout breaks", cp.stderr + cp.stdout)
self.assertEqual(cp.returncode, 0, cp.stderr[-1500:])
+ def test_a_check_that_ends_on_a_stuck_page_is_not_a_layout_break(self):
+ """check's --json on a stuck page is a report with one page_stuck finding (SHOWTIME_TEST_CHECK_STUCK fails every
+ seek at its deadline): the layout check reads its findings, finds no layout error, notes that check stopped
+ early and the render goes on."""
+ proj = self.tmp / "p"
+ proj.mkdir()
+ (proj / "showtime.json").write_text(json.dumps({"width": 1280, "height": 720, "fps": 30, "duration": 2}), encoding="utf-8")
+ (proj / "index.html").write_text(SIZE_PAGE % ("", "Fine"), encoding="utf-8")
+ cp = subprocess.run([sys.executable, str(LAUNCHER), "render", str(proj), "--size", "9:16", "--to", "0.5", "--quiet"],
+ env=dict(ENV, SHOWTIME_TEST_CHECK_STUCK="1"), stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+ encoding="utf-8", errors="replace", timeout=600)
+ out = cp.stderr + cp.stdout
+ self.assertNotIn("Cannot read properties", out)
+ # check's own error is not swallowed: one note says it stopped and the render goes on
+ self.assertIn("showtime render: note: check stopped early: the page's seeks stopped finishing: ", out)
+ self.assertIn("; rendering on", out)
+ self.assertNotIn("the layout breaks", out)
+ self.assertEqual(cp.returncode, 0, cp.stderr[-1500:])
+ # the check ended on the stuck page: a check that ran to its end writes its report (index.html: no page name)
+ self.assertTrue((proj / "work" / "render-check-1080x1920").is_dir(), sorted(p.name for p in (proj / "work").iterdir()))
+ self.assertFalse((proj / "work" / "render-check-1080x1920" / "report.json").exists())
+
if __name__ == "__main__":
argv = [a for a in sys.argv if a != "--fast"]