just native-skin-children --parent button queries the partial 9246 native child manifest. just skin-child-readers --class CSkinButton exposes static reader leads; just skin-child-probe and just skin-child-trace reproduce the isolated relationship tests; just skin-child-check validates the saved evidence without vendor execution. See Native Skin Child Relationships.
just offline-skin-host prepares/runs the native headless rendering experiment; just offline-skin-host-check validates the saved frame without executing vendor code. just offline-skin-composition prepares/runs fixed composition fixtures or shows saved native trees (show --case nested_relative); just offline-skin-composition-check checks their hierarchy, class merging, coordinates and layout round trips. Scope and dependencies: Offline Skin Host.
XML spike: just offline-xml, just offline-xml-trace, and just offline-xml-check prepare/run fixed inputs, trace native calls, and validate saved evidence. See Offline XML Parser.
The offline parser host uses a copied,
build-pinned executable to parse a fixed script suite in sandboxed subprocesses.
just offline-parser-check validates saved comparisons and converter rejection
tests without loading vendor code; just offline-parser prepare and run are
explicit experimental operations. Source: offline_parser.py and
plugin/offline_parser_host.cpp.
For the symbol-rich 9246 host, prepare_symbol_parser.py --app APP --check
reproduces the named parser manifest (optional capstone/numpy dependencies).
Preparation chooses each build's own guard manifest; the checker labels 9246's
comparison with the saved 9644 live baseline as cross-build.
Scripts supporting the reference. Two groups: offline tools that run against repo content only (safe anywhere, wired into just check), and extraction tools that read a local VirtualDJ install (macOS, Apple Silicon) and are version-pinned.
| Tool | Purpose | Recipe |
|---|---|---|
task_queue.py |
Parses the TODO.md task queue (and validates HISTORY.md, where Done tasks move, and RETIRED.md, the Retired queue it replaced): one Status: line per task, one state word from the closed vocabulary (Ready/Blocked/Conditional/Parking lot/Done/Retired), explanations in the Note: paragraph below. Backs just next-task / just task-queue / just status, and refuses to select when any status is unreadable rather than skipping the task. selftest runs the fixtures in tests/todo-status/. |
just next-task, just task-queue, check + selftest in just check |
probe_arg_positions.py |
Asks which argument POSITIONS a verb reads, which no other prober can see: holds a verb's attested shape and varies one position within its own class, so a changed answer means that position is read. Query-only, and it re-reads the baseline last so a drifting verb is reported unstable rather than scored as reading everything. Writes tests/verb-arg-positions.json. Holds each of the named states from fixtures.py and records by_fixture/seen_in per position, because the first capture was taken in ambient state and did not reproduce. A reads candidate has its baseline sampled across ~1s before it is believed (blink alternates on a timer and scored reads twice, on different positions). A keyword position needs TWO keywords to vary between, so --keywords widens the second word's source beyond the attested tails to the vendor's own parameter list (placeholders and refuted tokens removed) and, opt-in, the shared enumerations; every value carries the source that supplied it and the summary splits verdicts by the weakest one involved. --plan reports what a run would reach without a live instance. |
just probe-arg-positions [--keywords=…], just probe-arg-positions-plan, just verb-arg-positions <name>, --check in just check |
probe_bpm_transition.py |
Discriminates auto_bpm_transition's three documented parameters by where the pair of decks settles, not by whether a transition is running — the observable the earlier sweeps had, which cannot see which BPM the verb targets. Builds three distinct landmarks (a 100 BPM track on deck 1, a 120 BPM track pitched to 132 on deck 2, both stopped so it makes no sound), generating the second tempo since one tempo cannot separate a source original from a target original. Waits for the previous transition to disengage before every form — the verb is a toggle, and a form left running makes the next one stop it instead of starting one. Two runs with the order reversed. Writes tests/bpm-transition-forms.json, whose recognized-… forms feed the catalog cross-check. |
just bpm-transition, --check in just check |
probe_known_positions.py |
Establishes the known_positions fixture (cue, loop start, loop end at three distinct positions, deck stopped), proves every position with an oracle that is not get_time, probes every get_time tail against two nonsense controls, moves one position while holding the rest, and restores the deck. Two runs with the form order reversed. Writes tests/get-time-positions.json. |
just known-positions, --check in just check |
download_sdk.py |
Fetches the Atomix plugin SDK headers into vendor/vdj-sdk/ and writes a SOURCE.txt stamp (URL, date, sha256, contents) — the headers are unversioned inside the archive, so that stamp is the only record of which SDK a plugin was built against. Refuses a response that is not a zip, flattens entries and takes only .h, and verifies vdjPlugin8.h arrived. Not vendored in git: no license text, no stated terms. --check backs the doctor's SDK row. |
just download-sdk [--force], just doctor |
doctor.py |
Environment health in one screen, brew doctor style: the interpreter and whether it imports every distribution in requirements.txt, uv's presence, the installed VirtualDJ build against the builds the artifacts stamp (filename-pinned ones flagged as deliberately historical), and whether the live probe channel answers. Only the python section fails — the rest are notices, and the channel one sorts the queue into desk work and live work. --deps-only is the hermetic subset that runs first in just check, because the binary readers do not all fail loudly without numpy: extract_action_catalog.py caught the ImportError alongside a genuinely absent app bundle and silently promoted 30 of the vendor's own example placeholders into the probe worklist. |
just doctor, just install, --deps-only first line of just check |
check_reference_status.py |
Doc consistency: coverage-count cross-checks, broken local markdown links, test-fixture inventory completeness, no tracked Python cache files. | in just check |
lint_pads.py |
Pad XML: well-formed, <page> root, unique non-empty name, pad_page targets resolve, no filter_selectcolorfx inside query="". |
in just check |
lint_skins.py |
Skin XML vocabulary check: every element and per-element attribute must appear in the shipped-skin corpus (Built-In + SDK example); unknowns get closest-match suggestions. Catches the class of typo Atomix itself shipped (ction=, hightlight=), which the VirtualDJ parser silently ignores. Elements with class="" skip attribute checks (define-placeholder passing is arbitrary). Checks structure first against the parser's demonstrated tolerances, not the XML spec: shipped skins load with raw & in values, open/close tags differing in case (<Tooltip>…</tooltip>), duplicate attributes, and stray text before the root, so a stdlib parser, which rejects most of the shipped corpus for those, is not used; an unterminated tag, comment or quote, an unmatched close tag, an unclosed element or no root is an error and fails the run. Pass file paths to lint generated skins; --strict fails on findings. |
just lint-skins [paths], in just check |
lint_script.py |
Static VDJScript check, for a script string or the action/query/visibility attributes, backtick segments and pad bodies inside XML. Rules come only from settled records, and each finding cites its source: errors (unterminated quote or backtick, unbalanced parens, empty ternary branch, a Disproved name), warnings (a name absent from the build-stamped verb table, && before an action, a && b ? …, unsigned beatjump, a backtick argument to loop/beatjump/phrase_sync, sampler_loaded <n> 'auto', a string stored in a variable, a truthiness-trap condition, a literal branch, a comment marker, an unknown deck target), and notes (a chain trailing a ternary, a dual verb that read false only at rest). --corpus runs it over the vendor corpus by rule; its remaining errors are vendor mistakes, recorded in HISTORY task M2. Rule cases in test_lint_script.py. |
just lint-script --script "…", --xml FILE…; --repo and the tests in just check |
lint_mappers.py |
Mapper XML: <mapper device> root schema, <map value action> structure, unknown attributes. The script in each action is lint_script.py's job, against the verb table: the doc-derived index this linter used to read still listed names the binary disproves. |
just lint-mappers [paths], in just check |
extract_skin_readers.py |
Writes tests/skin-reader-vocabulary.json: what the binary's skin XML readers actually compare against (skin_object_base, element_dispatch, panel_builder), each name classified against the shipped corpus and the SDK doc. Build-anchored — --check skips itself when CFBundleVersion changes rather than failing. This is where clickthrough came from. |
just skin-readers / skin-reader <name> / skin-candidates, --check in just check |
extract_xml_inventory.py |
Writes the data artifact docs/skin-xml-inventory.json: element×attribute usage across XML corpora, cross-checked against the docs. Skin elements retain source files by kind (builtin, addon, official_example, project, fixture); deliberate negative controls are excluded. Tolerant tokenizer (skin XML is not always well-formed). --check fails on newly undocumented elements. No Markdown view — query with xmldb.py. |
just inventory, --check in just check |
extract_verb_index.py |
Generates docs/vdjscript-verb-index.json: machine-readable verb index parsed from docs/VDJScript Verbs.md (curated entries, catalog rows, alias table) unioned with the audit's official 991-name list. Consumed by verbdb.py bootstrap. --check fails when stale. |
just verb-index, --check in just check |
fxdb.py |
Query API over the swept native effects catalog tests/fx-introspection-dump.json: get <effect> (spelling-tolerant, resolves aliases; bare fxdb.py <effect> works too), search (filters: --min/max-sliders, --min/max-buttons, --has-slider=LABEL, --has-button=LABEL, --category=deck_fx|video_fx|transition, --has-length, --in-cycle, --name-only, --format=json), stats, check. get warns before answering when the asked name is one the sweep could not resolve, so a near-miss match (Brake → Beat Brake) cannot pass for a real selector name. No put — effect structure is machine-derived; re-run the sweep to refresh. |
just get-fx, just list-fx, just fx-stats; check in just check |
verbdb.py |
Verb record store API over docs/vdjscript-verbs.json (authoritative, hand-editable; a bare verbdb.py <name> is shorthand for get): get/put/next-incomplete/stats/search/check, plus bootstrap (merge-safe seed from the index + coverage audit + tracker). Replaces the record-then-promote-to-three-docs cycle with one put. put refuses an unknown name with did-you-mean suggestions so a typo cannot mint a junk record; a genuinely unofficial name (scope wrapper, hidden candidate) needs an explicit --new, which records it as tier=unofficial, official=false rather than silently claiming official status. evidence= appends one entry verbatim (it is prose, so it is not comma-split); aliases=/surfaces= still take comma lists. search filters on surface/section/tier/status/kind with --format=json, and with neither term nor filter lists every record — untruncated, as list-fx and list-skin-elements do; reports are queries on stdout — no derived Markdown is written to disk, and nothing can go stale. check validates schema, alias resolution, index coverage, and count freshness. |
just get-verb, just list-verbs, just put-verb, just next-incomplete-verb, just verb-stats; check in just check |
| topic.py | Cross-corpus topic search: one term → matching verbs (store), effects (FX catalog), skin/pad XML elements (inventory), the real example files that use them (ripgrep with word boundaries, ranked by coverage), topical docs, and local-test quirks/candidates. Pure aggregation over the already-gated stores — no artifact of its own, nothing to hand-tag; everything is derived from section, inventory families, and grep. check is a cross-store smoke test (schema drift upstream would break it). Known gap: elements whose family topic is not in their name (waveform's rhythmzone etc.) are reachable only via the DOCS pointer until items carry topic tags. | just topic <term> [--format=json --limit=N]; check in just check |
Regenerate order after editing verb docs or XML corpora: just verb-index && just inventory && just check.
These drive a running VirtualDJ over the HTTP control interface (just vdj-up to check reachability). They change live app state and their output is committed evidence, promoted with a Local test label — not directly authoritative docs.
| Tool | Does | Output |
|---|---|---|
sweep_verb_existence.py |
Queries every store name plus the candidates-doc names bare and buckets the HRESULT: a value (query verb), E_NOTIMPL (action-only), E_INVALIDARG (takes arguments), E_ACCESSDENIED (context-gated), S_FALSE, or E_FAIL (unresolved). Read-only. Proves existence and kind, NOT behavior — never a substitute for a recorded local test. Query it with just verb-probe <name>. |
tests/verb-existence-sweep.json |
sweep_fx_introspection.py |
Enumerates the enabled cycle for all three targets (deck FX / video FX / transition), resolves every known name to its canonical spelling via get_effect_title, then reads counts, short/full labels, normalized defaults, live value text, and length/beats flags per effect. Introspection is read-only — the get_effect_* helpers accept an effect name in place of the slot, so no selection is needed except for the two names get_effect_title is blind to. Restores the video-FX and transition selections it changed. |
tests/fx-introspection-dump.json |
These speak the VirtualDJ Remote protocol — a separate
channel from the HTTP interface, on Bonjour _vdjremote8._tcp / port 4243. Roles are
inverted: the device is the TCP server, so both tools act as a device and VirtualDJ dials
in. Pair them with an advert (dns-sd -R "iPad" _vdjremote8._tcp . 4243, using a name
VirtualDJ already lists); if it does not dial, drop and re-add the registration.
| Tool | Does | Output |
|---|---|---|
vdjremote_dial.py |
Dials a real Remote device (which speaks first) and captures its opening handshake, or --decodes a saved capture into a frame listing. The only step needing a phone/tablet. |
tests/vdjremote-opener.bin |
vdjremote_subscribe.py |
Impersonates a device: reuses a capture's setup/info/panel prefix, substitutes your own VDJScript subscriptions, and prints every pushed value. Needs no device. | stdout |
Read-only in practice — subscriptions only observe — but they do hold a live Remote session, and VirtualDJ lists the fake device in Config → Controllers → Phone/tablet until removed.
The fifth Tier-1 channel (task 10a). HTTP renders every answer to text; the C++ plugin
interface does not, so GetInfo (a double) and GetStringInfo (a UTF-8 buffer) are asked
separately and which channel a verb answers on is observed, with raw HRESULTs. Needs the
Atomix SDK headers under vendor/ — deliberately not vendored, see
Plugin SDK and .gitignore.
| Tool | Does | Output |
|---|---|---|
plugin/VDJIntrospect.cpp |
The plugin itself. Reads a probe list at load, calls both query callbacks per probe, writes the raw capture. Read-only by construction: the source contains no SendCommand call at all, so no probe list can reach execute position. Logs every DllGetClassObject negotiation, which is itself evidence for the open second-loading-path question. |
~/Library/Application Support/VirtualDJ/VDJIntrospect/{results.json,plugin.log} |
plugin/build.sh |
Builds and ad-hoc signs build/VDJIntrospect.bundle; --install copies it into the plugin folder. Command Line Tools clang++ is enough — no Xcode required. |
build/VDJIntrospect.bundle |
plugin_introspect.py |
prepare writes the probe list from the verb table; status shows the workdir and log tail; collect normalizes the raw capture (naming HRESULTs, classifying the answering channel); --get/--check query and gate it. --check passes with an explicit skip until the first capture exists. |
tests/plugin-introspection.json |
Order: just plugin-build --install → restart VirtualDJ → just plugin-prepare → restart
again (the sweep runs at plugin load) → just plugin-status → just plugin-collect.
Two things that bite. A capture costs a VirtualDJ restart only the first time — after the
delayed sweep runs, the plugin keeps a trigger loop alive, so just plugin-go re-sweeps
probes-late.txt within ~2s with no restart. That is what makes prepared-state work practical:
set the app up by hand (load a track, highlight a song), then trigger. And a load-time probe can be too early: OnLoad fires while VirtualDJ is
still starting, so an uninitialized subsystem (the browser) answers E_INVALIDARG exactly as a
nonexistent form would. Use prepare --late to write probes-late.txt, which the plugin
sweeps again ~40s after load from a timer thread, and re-take any negative there before
believing it. prepare --remaining emits the execute-capable keyword verbs (query position
only, unsafe families excluded and printed); just plugin-keyword-report <capture> splits
every keyword against its nonsense control.
Four independent sources, deliberately kept apart — they fail in different places, so
agreement is corroboration and disagreement is a worklist. just action-catalog --cross-check
prints all three against each other.
| Tool | Source | What it proves |
|---|---|---|
extract_action_catalog.py |
Resources/languages.zip — the same prose the official appendix publishes |
What a parameter means. 816 descriptions, 97 with parameters. Offline. |
element_summary.py |
The XML inventory, its docs, the reader vocabulary and the skin probe fixtures, joined per element | Nothing new — the counterpart to verb_summary.py. Adds the per-element attribute documentation gap the inventory cannot see: its documented flag covers the ELEMENT NAME only, so an element reads documented while the attributes shipped skins write it are unexplained. Separates template parameters from real gaps — <panel class="rm_hc" action1="hot_cue 1"> instantiates a template and action1 is substituted for [ACTION1] before any reader sees it, so it is author-invented and can never be reader vocabulary; detected by the corpus writing [NAME] for it, which is the substitution's own evidence. Without that split the metric overstates badly. A miss reports any live probe that already tested the name, so a refuted candidate answers with its evidence instead of a spelling suggestion. just element <name>, --format=json. |
verb_summary.py |
Every artifact above, joined per verb | Nothing new — the existing evidence read together, tiers stated. just verb <name>. |
coverage_report.py |
Every artifact above, joined per dimension | Nothing new — contract coverage recounted from the artifacts' own records, never from their stored summaries (and it names a summary that has gone stale). Four dimensions with per-dimension denominators: query return type, argument tails, execute-position behaviour, live-confirmed behaviour. States distinguish asked and inconclusive from never asked, and flag argument facts that reached the store's evidence prose without ever reaching an argument artifact. just coverage, --settled, --frontier, --format=json. |
extract_attested_tails.py |
Tails and SHAPES inside vdjscript-corpus.json |
That a token is used by the vendor, and — for value arguments — the arity and token types (fadeout DUR DUR BT) with the return type the vendor's attribute implies. Needs no probe, so it reaches where fixtures cannot. |
extract_binary_vocabularies.py |
Pointer tables and switch functions in the app binary | That a token belongs to a shared enumeration — and what the rest of the enumeration is. The only source that sees vocabulary matched in a helper rather than in the verb's own code (colour names, stem names, settings pages). Tier 2: members are leads. just binary-vocab --get stems. |
sysicon_atlas.py |
Dated wiki atlas, resolver branches and saved rendering results | Picture-to-key lookup with separate tested keys, binary candidates, state graphics and unknowns. just sysicon-atlas --cell H6, --unnamed, --format json. --extract captures internal atlas consumers; it does not run the app. |
probe_arg_forms.py |
The running app over HTTP | That a token is not nonsense, in a state where it could show. Needs just vdj-up. |
probe_arg_forms.py takes candidates from any of the three: --from-catalog (documented),
--from-corpus (attested), --lexicon N (tokens already proven on more than one verb), or the
binary's own keyword_candidates by default. --merge FILE folds a targeted re-probe into the
artifact — it unions form lists rather than replacing them, and requires the incoming run to
use a superset of the artifact's fixtures, since a verdict computed under states the base
never saw is not comparable.
Rules these tools encode, each learned by getting it wrong first:
- Two nonsense controls, not one. They must agree with each other, or the reading is
unstablerather than scored. - Separation is positive evidence; failure to separate is not evidence of absence. It usually means the states did not discriminate.
--repeat Nfor fast drift, two independent runs for slow drift.get_cpupassed--repeat 3and still flipped between runs.- A verb matching most of an arbitrary vocabulary is drifting, not speaking it —
_flag_undiscerning, which caughtrecord_vu(24 of 25 tokens) andget_time.
probe_execute_forms.py measures tails in execute position, where the query path is blind.
It writes to a live instance, so it is allowlist-only (name, category and audible deny-lists),
round-trips every verb before probing, restores and verifies each value, and aborts on a failed
restore while keeping the results already collected.
check_corpus_parses.py sends every corpus snippet through /query and classifies the
outcome — the one check here that can falsify a grammar claim rather than extend one.
fixtures.py provides the 10 named states these probes run inside (just fixtures). Each
asserts its own preconditions and fails loudly: a probe against an unestablished state is worse
than no probe. Several are assert-only — they read state the app already has rather than
writing, which is the right trade when there is no verified way back (browser_populated).
These read /Applications/VirtualDJ.app (override with --app). They need macOS with Apple Silicon tooling (nm, c++filt, otool, strings) and produce evidence, which is hand-promoted into the docs with source labels — their output is not directly committed.
| Tool | Reads | Build sensitivity |
|---|---|---|
extract_vdjscript_symbols.py |
Demangled ACTION_*::onExecute/onQuery* symbols from the executable |
Works per-build; symbol names may drift |
extract_vdjscript_catalogs.py |
Resources/languages.zip action tags + executable string table, diffed against the coverage audit |
String-block sentinels (action_deck…zoom_vertical) are content-anchored; verify hits on a new build |
extract_vdjscript_taxonomy.py |
Compiled Button Editor taxonomy tables via a hand-rolled Mach-O parser | Hard-pinned: default virtual addresses are for VirtualDJ 8.5.9307 / bundle 18.0.9336; on any other build you must re-derive addresses and pass --*-va flags |
disassemble_vdjscript_parser_targets.py |
otool -tV disassembly of eight DLGActionWizard parser/highlighter symbols |
Breaks if symbols are stripped or renamed |
extract_vdjscript_metadata.py |
Joins the four extractors into one summary/CSV | Inherits all of the above |
extract_action_vtables.py |
Every ACTION_ vtable slot resolved to a named method |
Needs an unstripped build. 18.0.9246 is the last one (321,571 symbols); 18.0.9482 onward keep ~1,210 and the tool exits rather than report nothing |
extract_script_corpus.py |
Catalog snippets + shipped Built-In XML + factory controller mappings (from the decoded archive matching the installed build, or --controllers <key>) + wiki transcriptions + statements compiled into the binary's __cstring pool. Stamps summary.factory_archive. |
Re-extracts and compares in just check, so a VirtualDJ update fails loudly rather than drifting; the factory check verifies the stamped archive and reports-and-skips when this machine holds a different build |
controller_archives.py |
Names a decoded controllers.dat by app build and archive revision (18.0.9598-r2241), lists every committed manifest under tests/controllers-manifests/ and which trees are decoded locally. Imported by the reader, the corpus extractor and the diff. |
just controllers-archives |
controllers_diff.py |
Added, removed and changed members between two builds' archives, from the committed manifests alone (per-member SHA-256, bytes, root attributes); --root, --format=json, --show-paths for the decoded pair when both trees exist. |
just controllers-diff <older> <newer> |
extract_binary_vocabularies.py |
ADRP+ADD code references and const char *[] tables, decoded with numpy over the arm64 slice |
Build-independent by construction (no fixed addresses), but the seeds in SEEDS are hand-named; a new enumeration needs a seed or a shared attested tail to be found |
Usage examples live in the docs that consume them: docs/Button Editor Taxonomy.md, docs/Button Editor Catalog Audit.md, docs/Undocumented VDJScript Candidates.md, docs/VDJScript Syntax Evidence.md.
When the installed VirtualDJ updates (check with defaults read /Applications/VirtualDJ.app/Contents/Info.plist CFBundleVersion):
- Refresh the shipped copies using the commands in each provenance README, then review diffs and update the version/date lines there:
examples/Pads/Built-In/README.mdexamples/Skins/Built-In/README.mdexamples/Samplerbanks/Built-In/README.md(Copies may intentionally lag the installed build; each README records which bundle its files came from. As of 2026-07, pads/skins are from bundle18.0.9336while samplerbanks are from18.0.9482.)
- Re-run the offline suite —
just verb-index && just inventory && just check— and resolve anything the inventory or link checker flags from the refreshed XML. - Re-anchor the binary tools if you need fresh compiled-table evidence:
extract_vdjscript_symbols.pyandextract_vdjscript_catalogs.pyusually work as-is; forextract_vdjscript_taxonomy.py, re-derive the three table addresses for the new binary and pass them via--*-va(the process notes are indocs/Button Editor Taxonomy.md). Update the Evidence Baseline block (version, bundle, SHA-256) indocs/Undocumented VDJScript Candidates.md. - Refresh the coverage audit only when intentionally re-fetching the live official appendix;
docs/Official VDJScript Coverage Audit.mdrecords its own refresh date, andcheck_reference_status.pykeeps the counts consistent afterwards.