t1k:playablelabs:web:params-audit
| Field | Value |
|---|---|
| Module | web |
| Version | 1.18.2 |
| Effort | medium |
| Tools | — |
Keywords: dead parameter web, param audit adapter, probe params runtime, three.js parameter wiring, web param audit
How to invoke
Section titled “How to invoke”/t1k:playablelabs:web:params-audit[patterns | spans | probe | tests]Web params audit: adapter and runtime probe
Section titled “Web params audit: adapter and runtime probe”The web host’s implementation of the adapter interface in t1k-playablelabs-base-params-audit/references/cache-contract.md.
The core (base module) owns cache, dirty set, status and report; this skill reads a three.js game’s parameter wiring and
runs the browser probe. detect(root): package.json lists three, not a Cocos project. Committed: .param-audit/status.json,
probe.json (hand-authored). Gitignored: cache.json, report.json, probe-results.json, local/.
bun <base>/scripts/param-audit.cjs --root <gameRoot> --adapter <web>/scripts/web-adapter.cjs [--no-write] [--json]bun <web>/scripts/web-probe.cjs --root <gameRoot> --init # scaffold probe.json (audio exemptions only)bun <web>/scripts/web-probe.cjs --root <gameRoot> --serve <builtDir> --playwright-dir <packer>/node_modules/playwright-core \ --keys @.param-audit/report.json # or --keys Vol,Dead; also --no-visual, --no-isolateFiles: scripts/web-adapter.cjs (adapter interface plus suggestVisual, defaultOf); scripts/lib/:
config-params (flat config object, entry text, defaults, audio class; ambiguous-config, exit 2, when two files declare it: remove the
nested clone or backup), categories, shared-constructs (shared-unparseable on unknown loop shapes), handlers, readers (evidence and
scene NULL-REF), facts, spans, span-helpers, probe-* (runtime probe, entry web-probe.cjs).
Executed by
Section titled “Executed by”The mechanical steps (running scripts/web-probe.cjs and its selftests, and reading the audit status it writes) are run by the cheap-tier t1k-tester agent. The verdict and any dirty-set decision stay with the calling agent.
Patterns
Section titled “Patterns”| pattern | source shape | mechanism | status when proven |
|---|---|---|---|
| A sink | K.onUpdate = d => Obj.field = d.default | direct-onUpdate, sink | WIRED-OK if field is read outside the write; else LOGIC-DEAD |
| A call | ... = d => Svc.method(d.default) | call-sink | WIRED-OK if method is defined in the tree; else UNKNOWN |
| B binder | onUpdate = () => this.node ? this.pushUi(K.applyTo(this.node)) : warnNull(...) | binder | WIRED-OK if the field is bound in the scene; NULL-REF if null or dangling; UNKNOWN if not a @property |
| C empty | onUpdate = () => { /* read elsewhere */ } | empty-handler | INTENTIONAL-EXTERNAL if read elsewhere; else NO-OP |
| D category loop | Object.entries(Cfg).forEach(...) if (!pred(p.category)) return; p.onUpdate = ... fire(new Sig(key)) | category-loop | WIRED-OK if a subscriber to Sig exists; else LOGIC-DEAD |
| E audio loop | same, if (p.category !== 'Audio') return; | audio-loop | WIRED-OK if the clip name is a literal elsewhere; else UNKNOWN |
| F bindAll | PlayableFeatures.bindAll({config: Cfg, ...}, FLAGS) | bindAll | WIRED-OK if package code references the key; else UNKNOWN |
| G global | onUpdate = () => window.__x?.refresh?.() | global-refresh | WIRED-OK if window.__x is assigned; else NO-OP |
| H read at use | no onUpdate; Cfg.K.default read elsewhere | read-at-use | WIRED-OK if read; else UNWIRED |
A direct handler that a covering loop runs after gets DIRECT-SHADOWED; an unresolvable category gets CATEGORY-UNRESOLVED.
readSpans(ctx, key): the key’s entry, referenced declarations, apply sites, covering constructs (predicate and signal
declarations), subscribe, literal and package lines, each reader’s enclosing method, a binder field’s scene value.
reads.tokens holds the key and the member, method, field, global and signal names used; the core diffs their counts. Test code (tests/, *.spec.*, *.test.*) and generated JSON are not evidence.
Probe manifest .param-audit/probe.json
Section titled “Probe manifest .param-audit/probe.json”Array or { "entries": [...] }, one entry per key; no entry means unclassified (unprobed).
| entry | fields |
|---|---|
| visual (default) | key, field?, values (>= 2 distinct), stateExpr (page expression reading the state the key moves), region |
| not-visual | key, visual: false, reason = audio | sdk | store-link | logic-only | other:<text>; nothing else |
Optional on a visual entry (validated, part of the entry hash): setup (page expressions, in order), waitFor (polled
until truthy, up to waitTimeoutMs, default 10000), freeze + unfreeze (a pair; unfreeze always runs after the driven
shot), settleMs (after each drive, default 500), viewport {w,h} (default 1280x720), stateWaitFor (polled before each
state read), stateSettleMs (default 0), mode: "preboot", captureAtMs. stateExpr may return a Promise; a read not
settled in 5000 ms is UNVERIFIABLE, never NO-EFFECT.
Region kinds (never the whole frame): dom {selector} (getBoundingClientRect); rect {x,y,w,h} (CSS px, w and h
positive, no round trip); eval {expr} returning {x,y,w,h}; three {boxExpr | objectExpr, cameraExpr}.
three: boxExpr returns the world box {min:{x,y,z},max:{x,y,z}}, cameraExpr an object with projectionMatrix.elements
and matrixWorldInverse.elements (16 numbers, column-major); the 8 corners are projected in Node onto the first <canvas>.
objectExpr takes the Box3 from window.THREE (absent: UNVERIFIABLE-visual). Exactly one of boxExpr/objectExpr; cameraExpr
always. A corner behind the camera (w <= 0) or beyond near/far is UNVERIFIABLE-visual. The real game exposes __THREE__: use boxExpr.
{ "key": "CtaScale", "values": [1, 2], "stateExpr": "__qa.cta().scale", "setup": ["__qa.win()"], "region": { "kind": "dom", "selector": "#cta" } }Validation is strict (exit 2, nothing merged): unknown reason or region kind, visual entry without region, not-visual entry
with values or region, duplicate key. A visual values[0] equal to the declared default (plain literals) warns on stderr.
Preboot (mode: "preboot": splash and intro params no __qa hook reaches, e.g. Preloader, IntroGif, EntranceMedia): each
load is a fresh page whose init script installs window.mainTheOneSdk.getParameterValue first ({ [field]: value } for an object
parameter, the bare value otherwise, null for other keys). controlA and controlB come from two loads at values[0], driven
from one load at values[1]; stateExpr and the region are read at the capture moment; captureAtMs (ms after navigation
start) catches a splash frame. Refused: setup, freeze, unfreeze, stateSettleMs, stateWaitFor. Unproven on a real build: that
the injected value survives the game’s own SDK bootstrap.
Runtime
Section titled “Runtime”- The page must expose
window.__qa.param(key, field, value)(build with?qa=1). Browser: newest cachedchromium-<rev>or--executable-path;playwright-corefrom--playwright-dir. Each visual key boots a fresh page unless--no-isolate. - State axis:
setup,waitFor, then per setstateWaitForandstateSettleMsbefore each read: APPLIED-OK, NO-EFFECT (detail names the cause;values[0]must differ from the default), WRONG-TARGET, UNVERIFIABLE (also a requested key with no entry). - Visual axis (only after APPLIED-OK): drive
values[0], settle, resolve region, shootcontrolAandcontrolB, drivevalues[1], settle, shoot driven. The core’svisualGatejudges the region only (union of the region at controlA and at driven, clamped to the viewport) against a bar calibrated by the controls. Off-screen is NOT-VISIBLE; a bad PNG or failed capture is UNVERIFIABLE-visual, never a pass.--no-visual: NOT-RUN, gate UNKNOWN, never clean. A key whose state axis failed is NOT-RUN, FAIL. Not-visual keys are not driven: named on stderr (web-probe: exempt <key> (<reason>)), no row. - Shots go only to
.param-audit/local/shots/<key>.{controlA,controlB,driven}.png. Output:.param-audit/probe-results.json(the core stores it instatus.json) and stdout, rows{ key, verdict, visualVerdict, gate }:visualVerdictVISIBLE | NOT-VISIBLE | UNVERIFIABLE-visual | NOT-RUN;gatePASS only for APPLIED-OK + VISIBLE, else FAIL (UNKNOWN under--no-visual). - Exit: 0 all PASS; 1 any FAIL or UNKNOWN; 2 usage, manifest or missing QA hook; 3 environment.
Tests and limits
Section titled “Tests and limits”bun test tests/*.test.cjs from the skill dir (fixture tests/fixtures/mini-web, edits in memory).
Call sinks are checked for a definition, not behaviour (the probe is the proof). Aliased reads (import {PlayableConfig as PC})
and bracket string keys are not seen. A binder field is read from scene JSON in ctx.files only; unscanned means UNKNOWN.