t1k:playablelabs:base:smoke
| Field | Value |
|---|---|
| Module | base |
| Version | 2.29.2 |
| Effort | medium |
| Tools | — |
Keywords: booted cta mraid ready, packer smoke, packer smoke contract, smoke-report.json, smoke.cjs
How to invoke
Section titled “How to invoke”/t1k:playablelabs:base:smoke--out <packed dir> --report <pack-report.json> [--networks ..] [--engine-host ..]Packer Smoke (scripts/smoke.cjs)
Section titled “Packer Smoke (scripts/smoke.cjs)”Contract of the PlayableLabs Packer’s headless-browser smoke: what a green row proves and how to run it.
Boundary: this is the packed artefact’s runtime check. Authoring Cocos game code is the Cocos kit’s; the
in-engine preview check is theonekit-gamedev’s (t1k-gamedev-playable-preview-verify); what a none/web game must publish to
boot is t1k-playablelabs-base-engine-hosts; the Jenkins wiring is the ci module’s.
Run it
Section titled “Run it”# from a SCRATCH dir, never the packer clone: --out-report defaults to ./smoke-report.jsoncd "$(mktemp -d)"bun <packer>/scripts/smoke.cjs --out <packed dir> --report <pack-report.json> \ --out-report ./smoke-report.json [--networks applovin,google|all] [--engine-host cocos-3.8|none|web]--reportis the pack report (pla-pack ... --json > pack-report.json), an INPUT: it lists the rows.--out-reportis wheresmoke-report.jsonis WRITTEN. Do not confuse them.- Needs a built packer (
bun install --frozen-lockfile && bun run buildin<packer>:dist/is read for adapters, policies, engine-host ids) andplaywright-corefrom the packer’snode_modules. --outmust be the flat tree:<out>/<network>/index.htmlorindex.zip(pla-pack --layout flat).- Pass the SAME
--engine-hostthe artefacts were packed with (defaultcocos-3.8). Run--helpfor the full flag list (timeouts,--mraid-scenario,--start-gate,--executable-path,--headed). --canary <json>is Cocos-only: refused (exit 2) with any host that carries no engine runtime (none,web).- Serving a build for a person to open in their browser (port check, path decoding, background start on Windows):
references/serve-a-build.md.
Exit codes
Section titled “Exit codes”| Code | Meaning | Action |
|---|---|---|
| 0 | every network passed | done |
| 1 | at least one row failed | read networks[].reasons in smoke-report.json; fix the artefact, not the harness |
| 2 | usage/setup error: bad args, unreadable report, zero rows, no Chromium, launch failed | fix the invocation; says nothing about the playable |
| 3 | all passed, but a --canary name is missing because the game switches its engine module OFF | warning only: summary.canaryWarnings |
Any other code (137 OOM, 124 timeout) means the run never finished: not a pass.
What a PASS row proves (and only that)
Section titled “What a PASS row proves (and only that)”A row passes when there are no uncaught page errors AND all three hold:
- BOOTED.
window.__smokeRaf__.count >= 3(rAF counter installed before any page script, soDEFAULT_BOOT_FRAMES= 3) AND the engine is running AND a scene is loaded withnodeCount >= 1. Cocos:cc.game.isPaused() === falseplusdirector.getScene()walked for nodes (scripts/lib/engine-probes-cocos38.cjs).none/web: the game’swindow.__plaGame__{running, scene, nodeCount()}(orwindow.__PLA_SCENE_UP__ === true) viaengine-probes-none.cjs. Not pixels, not size. - CTA THROUGH THE NETWORK API. Every network SDK global is stubbed before page scripts, each writing
window.__smokeCta__;window.openis stubbed too. After boot the driver sets synthetic store URLs onwindow.super_htmland callswindow.super_html.download(). Recorded: container call,window.open,postMessage "download", or (iOS-UA__plaOpenfallback) a main-frame navigation to a store host (ctaMethod: "navigation", then aborted).window.gameReadyis left undefined on purpose (Mintegral). - MRAID READY. The MRAID mock holds
loadingfor--mraid-ready-delay-ms(default 150), then firesready; the driver waits for it (awaitMraidReady, bounded by delay + 5 s) BEFORE the CTA. Calling a rich-media method (open,expand, …) before ready is a row FAIL (MRAID 3.0 s7.2). Other start-gate findings are WARN.mraid-ready-preloadis a packer start-gate policy exercised only by--mraid-scenarioruns; at4ee4272no network row resolves to it (all MRAID rows aremraid-ready-viewableormraid-sdk-ready).
A pass does NOT cover size, parity with another packer, or game logic past the first frames. It also does
not read the game’s OWN store link (the driver supplies synthetic ones), charset fragility, late container
SDKs or older WebViews: run scripts/audit-build.cjs on the same --out tree (references/build-audit.md).
Report
Section titled “Report”smoke-report.json: networks[] rows (booted, cta, ctaMethod, status, reasons, warnings,
errors, failedRequests, scene, mraid) plus summary {total, passed, failed, warned, canaryWarnings}
and allPass. A booted:false row carries the scene measurement behind it (no scene vs 0 nodes).
Verified against
Section titled “Verified against”PlaybleEngine@d76f263 (2026-10-07): scripts/smoke.cjs (header, helpText, parseArgs, main,
computeRowVerdict, mraidFindings, awaitMraidReady, stubInitScript, buildSmokeReport, exit constants),
scripts/lib/engine-probes-cocos38.cjs, engine-probes-none.cjs, Jenkinsfile/PlayablePacker
(smokeExitVerdict re-read at d76f263: 0 ok, 2 and 3 UNSTABLE, else error), src/adapters/networks.ts
(START_GATE_POLICIES, rows). git diff 4ee4272 d76f263 over src/, scripts/smoke.cjs and scripts/lib/engine-probes-*
is empty, so the 4ee4272 read of those files stands.
Executed by
Section titled “Executed by”Running scripts/audit-build.cjs and reading its report is mechanical, so a cheap-tier agent may do it. Whether a finding blocks a ship, and the repack that clears it, stay with the main session or a native agent. Routing SSOT: rules/orchestration-rules.md § “Task-Type → Agent Routing”.
Hard rules
Section titled “Hard rules”- Run from a scratch dir.
smoke-report.jsonlands in cwd by default; running inside the shared packer clone dirties it. Pass--out-reportexplicitly. Cap workers (<= 4) and one smoke at a time. - Chromium. The script does NOT use Playwright’s revision resolution: it picks the newest
chromium-<rev>under the browsers cache (~/.cache/ms-playwright;PLAYWRIGHT_BROWSERS_PATHoverrides). None found => exit 2. Install withbunx playwright-core install chromium, or pass--executable-path/PLAYWRIGHT_CHROMIUM_PATH. - Jenkins maps exit codes differently from “2 = bad”.
smokeExitVerdict: 1 and any crash code FAIL the build; 2 and 3 only mark it UNSTABLE. The stage runs only withPARAM_SMOKE(default off) and BEFORE the R2 upload stage, so a failing smoke (rc 1) stops the upload; an rc 2 does not. Smoke reads the flat layout only: with anotherPARAM_LAYOUTthe stage marks UNSTABLE and boots nothing. - A page error fails the row even if boot and CTA pass: read
errorsandfailedRequests(a >=400 response URL, since console text omits it). --network allrow count.allexpands to every row variant (orientation variants such asgoogle_portrait/google_landscapeand zip variants included), so smoke boots one page per row: budget the job time for it and readsummary.total, not a network count. A green smoke on that many rows is still not a size gate: size ispack-report.jsonemitted[].verdict.- A
webgame must set its own boot globals (__PLA_SCENE_UP__/__plaGame__, seet1k-playablelabs-base-engine-hosts, which also owns the CTA call order) or rows readbooted:false.