# IDE Automation
{: .no_toc }

Operates the twinBASIC IDE to test add-ins and the IDE itself, to try the help add-in by hand, and to take the documentation's IDE screenshots and review them. The command-line conventions every tool shares are under [Command-line conventions](/Documentation/Development/Tools.md#command-line-conventions).

* TOC goes here
{:toc}

## probe_theme_semicolon.mjs
{: #probe-theme-semicolon }

    node scripts/probe_theme_semicolon.mjs [--ide <twinBASIC.exe>]

Lists the properties that the twinBASIC IDE silently drops when it loads the theme files it ships. It is the check behind the `BUGS-TO-REPORT.md` entry whose reproducer is `bugs/theme-missing-semicolon/`: in BETA 1010, line 63 of `Dark.theme` and of `Light.theme` is `DiagnosticsGroupFontSize: 90%` with no `;`, so it runs into the next line, and the loader loses both `DiagnosticsGroupFontSize` and `DiagnosticsGroupFontWeight`. It starts no IDE and no program and writes nothing, but it needs an unpacked twinBASIC install. It is outside every gate and CI.

It reads every `.theme` file in the install's `themes` folder and cuts each one as `applyThemeData` in the IDE's `ide\main.js` does. The loader removes the `/* */` comments, cuts the text at each `;` followed by a space, a tab or a line end, removes the line breaks from each piece, cuts each piece at each `: ` and `:` followed by a tab, and keeps the piece only if that gives exactly two parts. Any other piece is dropped without a message.

| Flag | Effect |
|---|---|
| `--ide <path>` | Path to `twinBASIC.exe`, found as for `tbbuild`. The `.theme` files read are those in the `themes` folder beside it. |

The output is one line for each dropped piece that holds text, `<file> line <n>: dropped <what it holds>`, with the file relative to the install and the line where the piece starts. A piece made of several properties run together is shown as their names. The last line is a summary, `<n> properties are lost in <k> of <total> shipped themes (BETA <build>)`, or `no shipped theme loses a property (BETA <build>)`.

Exit codes: **0** every piece of every shipped theme loads; **1** at least one is dropped; **2** a refused command line, no IDE, no `themes` folder or no `.theme` file in it, or a crash.

## addin_test.mjs
{: #addin-test }

    node scripts/addin_test.mjs [--only <regex>] [--jobs N] [--timeout S]
                                [--ide <path>] [--show|--hide]

Runs the add-in scenarios under `test/addin/`. Each scenario file is a `node:test` file and one **lane**, listed in `test/addin/lanes.mjs`; run it with [`addin-test.bat`](/Documentation/Development/Tools.md#addin-testbat), because on its own a scenario skips itself. A lane runs in its own process, with its own slot from [`tbbroker`](/Documentation/Development/Tools-Compiler.md#tbbroker) (a private desktop), work folder and private copy of the twinBASIC install, so a test add-in never loads into your own IDE and two lanes never share one. Each IDE's DevTools port is one Windows picks.

A scenario builds the add-ins it tests into its copy, opens a project and operates the IDE: it clicks, presses keys, types, and reads the add-ins' tool windows, message boxes, notifications, the code editor and the Debug Console. The lanes take about two minutes together:

- **The sample lanes** operate the IDE's own sample add-ins, Sample 10 and Sample 15 (Global Search), end to end.
- **Probe lanes** take what they need from `test/addin/probes/`. They check:
  - which keyboard shortcuts fire, for the [KeyboardShortcuts](/tB/Packages/tbIDE/KeyboardShortcuts.md) page;
  - what a tool window does with HTML and with a web page in an `iframe`, for the [HtmlElement](/tB/Packages/tbIDE/HtmlElement.md) page and its neighbours (the panes lane serves its pages from a server of its own on `localhost`);
  - what the compiler says about the name under the cursor, and which files the IDE's web server serves from its `ide` folder;
  - which folders the compiler loads add-ins from, which folder each build target loads, what a compiler restart does to a loaded add-in, and which entry-point names the IDE accepts, for the [Add Ins](/tB/IDE/AddIns/index.md) and [tbIDE package](/tB/Packages/tbIDE/index.md) pages;
  - whether `TB_ADDIN_TEST` (see below) reaches the add-in, also after a compiler restart;
  - what the help add-in's hover help costs, and whether a hover provider added through the page shows in the IDE's own hover;
  - whether an add-in can show a window of its own, a form holding a WebView2 control.
- **The defect lanes** assert IDE defects that an add-in meets: what applying a panel layout does to an add-in's tool window, and what [DebugConsole.PrintText](/tB/Packages/tbIDE/DebugConsole.md#printtext) does with its colour argument.
- **The help lanes** test the help add-in in `add-in/`, built with the symbol index committed in `add-in/Resources/SYMBOLS/`. `help` takes the pages from the built site. `help-offline` takes them from the add-in's own server, built with an archive of the built offline tree that the lane writes with the build's [help archive](/Documentation/Development/Tools-Build.md#the-help-archive) writer.

| Flag | Effect |
|---|---|
| `--only <regex>` | Run only the lanes whose name matches. A lane's name is its file's name without `.test.mjs`. |
| `--jobs <n>` | Lanes at once. Default 2. Each lane takes its slot as it starts, and gives it back when it ends. |
| `--timeout <secs>` | A lane still running after this long is ended and counted as failed. Default 600. |
| `--ide <path>` | The `twinBASIC.exe` to copy, found as for [`tbbuild.mjs`](/Documentation/Development/Tools-Compiler.md#tbbuild). |
| `--show` / `--hide` | As for [`tbbuild.mjs`](/Documentation/Development/Tools-Compiler.md#tbbuild). |

**It puts the registry back as it found it, and checks.** Every IDE a lane starts is given `--no-save-ide-settings` and `--no-update-recent-files`, so it writes none of your IDE's options, recent-projects list or remembered build targets. The runner restores the project state, the file association and your IDE's window size and place as `tbbuild` does, and its last line says how many writes each took. It also restores the settings the add-ins under test save with `SaveSetting`. Those live under `HKCU\Software\VB and VBA Program Settings\<name>`, shared with any installed copy of the same add-in, so a lane names its add-ins' application names in `lanes.mjs` (`settings`). The runner records them before the first lane, deletes them before each lane that names them (so its add-ins start from their defaults) and puts them back at the end. Two lanes that name the same one never run at once.

Afterwards it confirms that no project-state or recent-list entry and no remembered build target names a lane's folder (the last two are only read, because an IDE with the flags writes neither) and that the settings are as found, and reports any new application key that no lane named. Ctrl+C ends the lanes and still puts everything back, as does a crash of the runner once it has recorded the registry.

**Every IDE a lane opens has a page of 1600 by 1000 CSS pixels.** The IDE opens its window at the size your own IDE last left it, so without a fixed size a scenario that clicks the toolbar or hovers in the code editor would pass on one machine and fail on another: in a small window a tool window floats over both. The lane fixes the page's size as soon as it attaches to the IDE. A lane in `lanes.mjs` can name another size with `page`, or `null` to keep the window's own.

**An add-in under test starts no browser.** Every IDE the harness starts, including those of `tbbuild`, `tbrun` and `check_examples`, has the environment variable `TB_ADDIN_TEST` set to `1`, and an add-in tested here is expected to check it. While it is set, the add-in prints `open <url>` to the Debug Console instead of opening a page, and a scenario reads the line there. A browser started on the harness's private desktop would open where nobody can see it and keep running.

**The add-ins you keep in `%APPDATA%\twinBASIC\addins` never load into a test IDE.** The compiler takes that folder from the IDE's `APPDATA` environment variable. Every IDE a lane starts has an `APPDATA` inside the lane's work folder, and a lane fails if its IDE's add-in folder is anywhere else.

Exit codes: **0** every lane passed, and the registry is as it was found; **1** a lane failed, or the run was interrupted; **2** the harness could not run: a refused command line, no IDE (or one older than BETA 1007), no matching lane, a registry it could not record, or a crash after which the registry was put back; **3** the registry or a work folder was not put back, or the recent list or a remembered build target names a lane's folder (see the lines above), at the end of a run or after a crash, which wins over a 1 because the registry is what to repair.

## ide_test.mjs
{: #ide-test }

    node scripts/ide_test.mjs [--only <regex>] [--jobs N] [--timeout S]
                              [--ide <path>] [--show|--hide]

Runs the IDE scenarios under `test/ide/`: the scenarios that operate the IDE itself, such as the debugger, Export Project and the Packages dialog, rather than an add-in. It is the same runner as [`addin_test.mjs`](#addin-test), with the same flags, lanes, registry handling and exit codes. Each file listed in `test/ide/lanes.mjs` is one **lane**, run by [`ide-test.bat`](/Documentation/Development/Tools.md#ide-testbat). Run on its own, a scenario skips itself.

The only difference is the suite. The rules of `addin_test.mjs` apply unchanged: every IDE has a private `APPDATA`, `TB_ADDIN_TEST` set to `1` and a page of 1600 by 1000, and an IDE is ended by its process id, never by its image name.

Exit codes: **0** every lane passed, and the registry is as it was found; **1** a lane failed, or the run was interrupted; **2** the harness could not run: a refused command line, no IDE (or one older than BETA 1007), no matching lane, a registry it could not record, or a crash after which the registry was put back; **3** the registry or a work folder was not put back, or the recent list or a remembered build target names a lane's folder (see the lines above), at the end of a run or after a crash, which wins over a 1 because the registry is what to repair.

## try_help_addin.mjs
{: #try-help-addin }

    node scripts/try_help_addin.mjs [--project <dir>] [--ide <path>]

Opens an IDE on your own desktop with the help add-in in `add-in/` built and loaded, to try it by hand, and waits until the IDE is closed. Run `build.bat` first: the pane's pages come from the built site, `docs/_site`, served on `localhost`.

The IDE is set up as a lane of [`addin_test.mjs`](#addin-test) is. The add-in goes into a private copy of the twinBASIC install in the temp folder, never into the install's `addins\` or `%APPDATA%\twinBASIC\addins\`, and the IDE has a private `APPDATA`, so none of your own add-ins loads into it. `TB_ADDIN_TEST` is `1`, so *Open in browser* prints `open <url>` to the Debug Console and starts nothing. This IDE is on your desktop; the IDE that builds the add-in first runs on a private desktop.

`--project` names the exported project to open, by default `test/addin/helphost`, the help lane's host. It is opened as a staged copy, so edits made in the IDE are not kept. Closing the IDE, or Ctrl+C, puts back the IDE's project state and file association and the add-in's saved settings (`tbDocsHelp`) and deletes the copy. The window's size and place are left as you leave them, since you move this IDE yourself, and the page keeps the window's own size.

Exit codes: **0** the IDE was closed, and the registry is as it was found; **1** the add-in did not build, or the project does not compile; **2** the tool could not run: a refused command line, no IDE, no built site, a registry it could not record, or a crash; **3** the registry or the work folder was not put back (see the lines above).

## shoot_docs.mjs
{: #shoot-docs }

    node scripts/shoot_docs.mjs [--only <regex>] [--out <dir>] [--diffs <dir> | --stage <dir>] [--events] [--jobs N] [--ide <path>] [--svg] [--bundles <dir>] [--against <rev> | --against-disk]
    node scripts/shoot_docs.mjs --cleanup [--dry-run] [--only <regex>] [--out <dir>] [--against <rev>]
    node scripts/shoot_docs.mjs --list [--only <regex>]

Takes the documentation's screenshots of the IDE, so that one run regenerates them after a new BETA. Each picture belongs to a *setup*, one IDE brought to a known state. A setup's IDE is started only when one of its pictures is selected. Run `build.bat` first: the help setup's pane pages come from the built site, `docs/_site`, served on `localhost`.

- **help** builds the help add-in in `add-in/` into a private copy of the twinBASIC install and opens the demo project `test/addin/helpdemo`. It takes the pictures of the [Help Add-In](/tB/IDE/AddIns/Help.md) page, `docs/IDE/AddIns/Images/Help_<Name>.png`.
- **no-project** starts the IDE with no project open: the menus under `docs/IDE/Menu/Images/`, and the dialogs that need no project --- New / Open Project and its tabs, the Manage Keyboard Shortcuts and Manage Panel Layouts dialogs, and the ones the FAQ shows.
- **project** opens the demo project without the add-in, for the dialogs that need a project open: About, whose licence line needs the compiler, and IDE Options, whose font lists do.
- **sample**, **settings** and **glyphs** open `test/shots/sample`, a small Standard EXE made for the pictures. They take the panels and the editor with a project, Project Settings (with the settings files of `test/shots/settings`), and the icons the pages show inline.
- Further setups each bring the IDE to one state the setups above do not need:
  - the Community Edition and LIMITED badges and the splash screen;
  - the icon of each control in the Toolbox, one picture each under `docs/Reference/Images/Toolbox/`, which the control's reference page and the [Controls](/tB/Controls.md) page show;
  - the programs under `test/shots/programs`, run so that their windows can be taken, and the CodeLens, TWINPACK build and Fusion pictures;
  - the package server's dialogs, which need the network and never publish anything;
  - the Import from twinproj dialog, for a VB6 project made for the picture (`test/shots/vbp`);
  - the Webpage pane showing this documentation's home page.
- **web** is a Chrome that the tool starts on a private desktop, not an IDE. It takes the two pages of Microsoft's and GitHub's sites that the FAQ shows, and needs the network.

Every IDE is set up as a lane of [`addin_test.mjs`](#addin-test) is, with a private `APPDATA` and `TB_ADDIN_TEST` set to `1`, and never appears on your desktop.

**Every run that would write under `docs` is a run of the review session** of [`shot_review.mjs`](#shot-review), whether it is typed in a terminal or started from the tool. When the review tool is open for the checkout, a run typed in a terminal is handed to it: it shows on the tool's runs page, and the terminal shows its lines until it ends. When the tool is not open, the run opens the session itself and runs as the tool would run it, with `--stage` and `--events`, applying each decision under `docs` as it arrives and recording the run, so that the tool shows it the next time it is opened. Either way the run is compared with the session's baseline, Ctrl+C stops it as the tool's **Stop** does, and a second Ctrl+C ends its process. Such a run refuses `--diffs`, `--bundles` and `--against-disk`, and an `--against` other than the baseline: they apply only with `--out` naming another folder, or with `--stage`. `--list` and `--cleanup --dry-run` write nothing and run as they are. The same holds for [`replay.mjs`](#replay) and [`chromeshot.mjs`](#chromeshot).

The pictures are repeatable. The IDE lays its page out at 100% whatever the display's scaling, the page has a fixed size of 1280 by 880 CSS pixels at 2x, and animations and the text caret are switched off. The IDE's options, panel layouts and keyboard shortcut groups are set to their defaults in the page only, and the recent-project lists are replaced there, so no picture shows your own choices or projects. Nothing is saved: the IDE is started with `--no-save-ide-settings` and `--no-update-recent-files`. A picture that shows the Debug Console has its line times set to fixed values.

Menus are cut out, transparent around the menu; dialogs are taken whole. A running program's window is taken once, not in two themes, at the display's scaling. Arrows, rings and numbered badges are drawn by the tool (`scripts/svgshot/annotate.mjs`), anchored to the element they point at, so a retake after a new BETA puts them where the element now is.

A picture is written only when it differs by more than the noise two captures of an unchanged screen show. The tool captures the page again and again, with no pause, until one capture is the picture as git has it at `HEAD` or the file already there, or two in a row are the same. When those two differ from both, it goes on capturing, further and further apart, for up to 5.5 seconds, and keeps the picture a capture equals, else the last two captures that agreed: some pictures are drawn in more than one version from one capture to the next, and some states take a moment to settle.

The capture is then compared with the picture at `HEAD` first. One that is that picture, or within the noise of it, leaves the file as `HEAD` has it, with its SVG (the one at `HEAD`, or none when `HEAD` has none), and is reported `restored` when the file held anything else. Comparing with the file alone, a retake over several runs could drift from the repository's picture in steps each within the noise of the file before it, or keep the other version of the noise. A capture that is not near the picture at `HEAD` is compared with the file: within the noise of it, the file stays, since an earlier run of the same retake wrote that change; else the file is written. A picture `HEAD` does not have is compared with the file only. Each picture is reported as `new`, `updated`, `restored` or `unchanged`; a second run with nothing changed reports every picture `unchanged`.

Each picture can have an entry in `test/shots/manifest.json`, keyed by its path under `docs` (a light picture's with `.light`). A run records there the twinBASIC build of each picture it writes. An entry can also change how its picture is judged. It can give the picture a noise rule of its own, with other limits or with rectangles, in the picture's pixels, left out of the comparison, and it can give the picture's SVG another bar. It can also hold a decision made in a review: to keep the old picture or take the new one, for one capture, or to accept or refuse one SVG compared with one PNG. A decision applies only to exactly the bytes it was made on, and any other capture is judged by the rule. `--cleanup` follows the same entries. A run into a folder other than `docs` neither reads the file nor writes it.

The Windows user name must never be in a published picture. Before each one is kept, the visible text of its page is searched for the name, and a picture whose page holds it is refused.

Every picture is twice the size it is shown at. A page that shows one gives it a `{:width
height}` of half its pixel size, so that it is sharp on a high-resolution display and in the book.

Every picture is taken in two themes by the same IDE: first in the dark theme, as `X.png`, then, with the IDE switched to its Light theme, as `X.light.png` beside it. The site shows the light picture in its light theme and the dark one in its dark theme, and the book shows the light one (see [A picture in both themes](/Documentation/Development/Authoring.md#a-picture-in-both-themes)). A light picture that looks exactly like the dark one is not kept. Labels drawn on a picture follow its theme.

The Light theme lays some of the IDE out a few pixels smaller, so a light picture can be a few pixels off the dark one's size. One more than 32 pixels off fails, because the IDE was not in the state the dark picture shows. The run ends with a count, for each theme, of the pictures that were new, updated, unchanged or the same as the dark picture.

Flags:

- `--only` takes the pictures whose path under the output folder matches a regular expression, such as `Menu_File` or `IDE/Menu/`, each in both themes. `--out` is the folder those paths are under, `docs` by default.
- `--diffs` names a folder, outside `docs`, for a difference picture of each updated picture: the file on disk, the new picture and their difference side by side, with the region that differs magnified underneath. A matching pixel is dark grey; a differing one is yellow for one grey level, shading to red for large differences. File names end in `.dark` or `.light`. A `.capture-<n>` file is written for each two captures of one state that disagree, a `.noise` file for a picture left as it is because it differs from the file only by that variation, and a `.restored` file, the file and the picture at `HEAD`, for a picture put back.
- `--against` names the git revision a capture is compared with first, `HEAD` by default; git runs in the `--out` folder, and reads the run's pictures in one process. With the default, an output folder outside git is compared with its files only; a revision given that cannot be read is refused. `--against-disk` compares with the file on disk only.
- `--cleanup` starts no IDE and no browser. Every PNG under the output folder that git reports modified against the revision (`--against`, `HEAD` by default) and that is within the noise of the revision's is put back as the revision has it, with its SVG as a restored picture's is, so that only real changes stay in the working folder. An added or a deleted picture, one that differs by more than the noise, and one whose SVG alone changed are real changes and are left alone. It prints each path it puts back and a count of those, the real changes and the added and deleted pictures it skipped. `--dry-run` lists them and changes nothing. `--only` chooses a PNG when the expression matches its dark path or its `.light.png`; `--out` and `--against` apply, and the flags that need an IDE are refused. The noise is the same test, in `scripts/lib/shot-change.mjs`, that the capture applies.
- `--jobs` is how many IDEs run at once, 6 by default and at most 16. Each runs on a private desktop (a slot from [`tbbroker`](/Documentation/Development/Tools-Compiler.md#tbbroker)) with a work folder and an install copy of its own, and a DevTools port Windows picks. The setups wait in a queue, the longest first, and the three long ones (no-project, sample and customcontrols) are cut into three parts, each in an IDE of its own. Every line of output starts with the setup or part it is from. `--jobs 1` runs each setup whole, one after another.
- The help setup's slot also carries a port from the broker for the add-in's detached window, which the add-in has to be told before it binds it. The add-in's saved settings (`tbDocsHelp`) are emptied for the run and, with the IDE's project state, put back at the end.
- `--svg` also draws each picture as SVG, from the page as it stands at the capture, and writes it beside the PNG as `X.svg` when it is close enough to the PNG (see [A picture as SVG](/Documentation/Development/Authoring.md#a-picture-as-svg)). An SVG already there is rewritten only when its PNG is. An SVG that draws exactly the same pixels as the revision's SVG (`--against`) puts the revision's bytes back, and one that draws the same pixels as the file's leaves the file as it is: bytes no one sees, such as the order of an element's attributes, are not kept. Both are drawn as the site shows a picture, at its device scale, and compared exactly; an SVG that stays with its PNG and draws as the revision's goes back to the revision's bytes too. It needs Python with fontTools. What the SVG is drawn from --- the page's layout, styles and measurements --- is saved for each picture as a *bundle* in the folder `--bundles` names, `.svgshot-bundles` in the repository by default, so that [`replay.mjs`](#replay) can draw the SVG again without the IDE. Git ignores that folder, and it must stay outside `docs`: a bundle holds the Windows user name.
- `--stage` names a folder, new or empty, outside `docs` and at a path git ignores, that takes everything the run would write: nothing is written under the output folder, to the bundle folder or to `test/shots/manifest.json`. Each picture's capture, its SVG whether or not it is close enough, its bundle, its difference pictures, its *strength maps* (how many levels each pixel is off the picture it was compared with, and the SVG's off its PNG) and what was decided about it go there, laid out as `scripts/lib/shot-stage.mjs` describes, so that another program can apply the decisions afterwards. With `--svg`, the SVG of a picture whose PNG is not written is judged and staged too, its decision *unchanged*, so that a program that takes the capture after all can write the SVG as judged. The lines printed say what was decided, as without it. It cannot be given with `--diffs` or `--bundles`. The fonts' cuts are still kept in the bundle folder's `subsets`, since a cut depends only on the font and its characters.
- `--list` starts no IDE and takes nothing. It prints the tool's table of pictures as one line of JSON: for each, the dark picture's path under `docs` (its light one is `X.light.png`, unless the picture is taken once), its setup, whether it is taken once, and whether it is of a running program's window, which has no SVG. `--only` applies, and every other flag is refused. A shot of a program's window says so in the table, and a shot whose capture and table disagree fails, so the list is always right.
- `--events` also prints a line for each event, `@@shot-event` followed by JSON: the run with its jobs and pictures, each job started, done or failed, each picture's verdict, each SVG's, a picture that failed or was not taken, and the summary. A picture's verdict says what it was compared with, its regions of change and whether it needs a person to look at it (`scripts/lib/shot-queue.mjs`). With `--events`, a line `stop` on standard input stops the run: no further picture is taken and no further setup started, and the IDEs end and the registry is put back as at the end of a run.

Exit codes: **0** every picture was written or was unchanged (with `--cleanup`, every modified picture was compared; a run stopped with `--events` exits as for the pictures it took); **1** a picture failed (an element was not found, the page showed the user name, or a light picture was more than 32 pixels off the dark one's size), the add-in did not build, or the demo project does not compile, or with `--cleanup` a picture could not be read as a PNG; **2** the tool could not run: a refused command line, no IDE, no built site, a registry it could not record, no such revision (or, with `--against` or `--cleanup`, no git repository), or a crash; **3** the registry or the work folder was not put back (see the lines above).

## replay.mjs
{: #replay }

    node scripts/svgshot/replay.mjs [--only <regex>] [--bundles <dir>] [--out <dir>] [--diffs <dir> | --stage <dir>] [--events] [--recheck] [--against <rev>] [--jobs N]

Draws each picture's SVG again, with the SVG converter as it is now, from the bundle that [`shoot_docs.mjs --svg`](#shoot-docs) or [`chromeshot.mjs`](#chromeshot) saved with the picture. It starts no IDE and takes no picture, so a change to the converter under `scripts/svgshot/` is tried on every picture in about 20 seconds.

Each SVG is compared with its PNG and written, left unchanged or removed as `shoot_docs.mjs` does. First, an SVG that draws exactly the same pixels as the SVG at the revision `--against` names (`HEAD` by default) puts that SVG's bytes back, and one that draws the same pixels as the file's leaves the file as it is, as `shoot_docs.mjs --svg` does. So a replay puts back the SVGs a run from a terminal rewrote in bytes alone. Git runs in the `--out` folder; a folder outside git is compared with its files only. An SVG that comes out the same as the file already there is not compared again, so a replay with the converter unchanged reports every picture `unchanged`. A picture whose entry in `test/shots/manifest.json` names its SVG is compared again all the same, and judged by that entry as `shoot_docs.mjs` judges it.

Cutting an SVG's fonts down to the characters it draws takes most of the time, so each cut is kept in the `subsets` folder of the bundle folder, named by a hash of the font, the characters and the cutting script. [`shoot_docs.mjs --svg`](#shoot-docs) keeps and reuses them the same way.

A bundle holds only what the converter asked for when the picture was taken. A picture is left as it is and listed as needing a retake when:

- its PNG has changed since its bundle was saved;
- its bundle lacks a computed style the converter now reads;
- the converter asks for something the bundle cannot answer, such as the width of a run of text it did not draw before.

The list ends with the `shoot_docs.mjs --svg --only` command that takes those pictures again.

`--only` takes the pictures whose path under `docs` matches a regular expression, a light picture's path ending in `.light.png`. `--bundles` is the bundle folder, `.svgshot-bundles` by default, and `--out` the folder the pictures are in, `docs` by default. `--diffs` names a folder for each SVG's difference picture against its PNG. `--recheck` compares every SVG with its PNG, also one that is the same as the file, for when the comparison itself has changed. `--jobs` is how many processes draw at once, each with a browser of its own, by default half the logical processors and at most 8. `--stage` and `--events` work as for [`shoot_docs.mjs`](#shoot-docs): the stage takes each SVG drawn, its difference picture, its strength map and what was decided about it, and nothing is written under the output folder; `stop` on standard input is passed to every process, and each draws no further SVG.

A replay that would write under `docs` is a run of the review session, as a [`shoot_docs.mjs`](#shoot-docs) run is.

The tool needs Python with fontTools, as `--svg` does, for a cut that is not kept yet.

Exit codes: **0** every picture was drawn again; **1** a picture needs a retake, could not be drawn, or its SVG holds a word no published picture may show (the Windows user name, git's `user.name` or `user.email`, or a word of `scripts/svgshot/private.json`); **2** the tool could not run: a refused command line, no bundle folder, no browser, or a crash.

## The svgshot Chrome extension
{: #svgshot-extension }

Takes a page in your own Chrome the way [`shoot_docs.mjs --svg`](#shoot-docs) takes the IDE's page: a PNG, and the bundle its SVG is drawn from, in a dark and a light picture. It is for a page that needs your own sign-in, which no tool can open: the six GitHub pictures of [Deploying to docs.twinbasic.com](/Documentation/Development/Building.md#deploying-to-docstwinbasiccom).

The extension is the folder `scripts/svgshot`. To set it up:

1. Copy `scripts/svgshot/private.example.json` to `scripts/svgshot/private.json`, which git ignores, and list the words no picture may show, each with what to show in its place: your e-mail address, your name, your GitHub login, and anything else that holds your Windows user name.
2. In Chrome, open `chrome://extensions`, turn on **Developer mode**, press **Load unpacked** and choose `scripts/svgshot`.

A [browser retake](#shot-review) of [`shot_review.mjs`](#shot-review), or [`chromeshot.mjs --take`](#chromeshot), keeps its own copy of the extension in `%LOCALAPPDATA%\svgshot\extension`, with your word list, and brings it up to date each time. Load that folder instead, which stays when a worktree goes; the tool says so the first time, and says when to press reload.

To take a picture:

1. Open the page and put it in the state the picture shows.
2. Press the extension's toolbar button. The side panel opens, and stays open while you work in the page.
3. Choose the picture, or **Another picture** and its path under `docs`. The panel says what each of the six must show.
4. Press **Whole viewport**, which takes what the window shows, or **Drag a rectangle**, then drag over the page. A click takes the box of the element under it, and Esc or **Cancel** gives up.

Take each of the six with **Whole viewport**, with what it shows in the window. [`chromeshot.mjs`](#chromeshot) trims the capture to the picture, so a retake is aligned as the last one was, however the page was scrolled. A rectangle dragged by hand comes out a little different each time.

Chrome shows a bar saying that the extension is debugging the browser, for as long as a capture takes. Leave it, and keep the tab showing. The page is put back as it was afterwards, and the file goes to the `svgshot` folder of your downloads as `<name>.capture.json.gz`, where [`chromeshot.mjs`](#chromeshot) reads it. A browser set to ask where to save each file asks for this one too. Each take, whether it worked or not, also saves `<name>.log.txt` there, with the time of each step, what was masked and any failure with its stack, its private words masked. A failed take saves no capture and leaves an earlier one as it was, so look at the file's time.

The capture does the following to the page:

- It lays the page out at 1x and draws it at 2x, as the IDE's pictures are. On a display scaled above 100% the tab's zoom changes for the capture, so the page is smaller for a moment. **Page width** lays the page out at that width in CSS pixels, and the six are laid out at 1280 unless it says otherwise, so that each retake has one layout. Without it the page keeps the width the tab gives it. A width that does not fit the tab is cut off on screen, so that **Drag a rectangle** cannot reach the part cut off, and **Whole viewport** still takes it.
- It replaces each private word in the page by its stand-in, in text, in text boxes, in a list's choices and in attributes, and shows a grey head in place of a picture whose address, alternative text, link or hover card holds one. The PNG and the bundle are therefore both of the masked page. Words the page draws again during the capture are masked again, and a capture they get into is taken again.
- It sets the theme with the `prefers-color-scheme` preference, and on GitHub with the attributes that hold the account's own theme.
- It draws the marks of the six pictures, in the style of the other pictures, which go into both the PNG and the SVG: a badge beside a ring, or beside a box round something tall. Where the page has nothing that a mark's table entry finds, the page asks you to click what the mark points at. **Draw the markings** turns them off.

The mask finds text. It does not find text inside a picture or a `<canvas>`, or in a frame of another site, so look at the preview the panel shows before you publish a capture.

## chromeshot.mjs
{: #chromeshot }

    node scripts/svgshot/chromeshot.mjs <capture | folder>... [--stage <dir>] [--events] [--against <rev>] [--out <dir>] [--bundles <dir>] [--diffs <dir>] [--words <file>] [--no-trim]
    node scripts/svgshot/chromeshot.mjs --take <regex> [--captures <dir>] [--extension <dir>] [--no-open] [--stage <dir>] [--events] [--against <rev>] [--out <dir>] [--bundles <dir>] [--diffs <dir>] [--words <file>]

Turns what the [Chrome extension](#svgshot-extension) saved into a picture. A folder stands for every capture in it. For each capture it writes `X.png`, and `X.light.png` when both themes were taken, as [`shoot_docs.mjs`](#shoot-docs) writes a capture: one within a capture's noise of the picture is not written, and a light picture with the dark one's pixels is not kept. It draws each SVG from its bundle, writes it beside its PNG when it is close enough to it, and keeps the bundle in the bundle folder, so that [`replay.mjs`](#replay) draws the SVG again after a change to the converter. The line for each PNG gives the `{:width height}` for the page that shows it.

A capture of the whole window, of one of the six, is cut down first. `scripts/svgshot/chrome/shots.mjs` names, for each picture, the elements it holds, by the same kind of anchor its marks use. The tool finds them in the page as the capture recorded it, takes the box round them and the marks, leaves 8 CSS pixels round that unless the table gives a side room of its own, and cuts both themes to it. The capture keeps the whole window, so a change to that table trims the same capture again, with no new picture. A picture whose area was not all in the window is refused, with the side to scroll to. A rectangle dragged by hand is left as it is, which the tool says, and `--no-trim` keeps the whole window.

A capture holds what the page held, so it stays out of the repository. The tool refuses one under `docs`, or where git would take it. It also refuses a capture of a bundle format the converter does not read, and one that shows the Windows user name, git's `user.name` or `user.email`, or a word of `scripts/svgshot/private.json`. Every capture is checked before any file is written, and [`replay.mjs`](#replay) makes the same check of each SVG it draws.

`--out` is the folder the pictures are in, `docs` by default. `--bundles` is the bundle folder, `.svgshot-bundles` by default, refused under `docs` and where git would take it. `--diffs` names a folder for each SVG's render, the picture drawn again as a PNG, and its difference picture, and the line for each SVG then says how far the render is from the screenshot by the rule for two captures. That rule allows no shift of a pixel for the edge of a glyph, so a faithful SVG does not meet it. `--words` names another list of private words, and `--no-trim` keeps the whole window of a capture.

The tool needs Python with fontTools, as `--svg` does.

**`--take`** helps you take the six, one after the other, those whose path under `docs` matches the regular expression. It brings the extension up to date in its own folder (`--extension`), opens the picture's page in the default browser (not with `--no-open`), tells the panel which picture is next, says what to set up, and waits for the capture in the folder your browser saves to (`--captures`; by default `svgshot` in Windows' Downloads folder). A capture arrives there when you press **Whole viewport**, and is treated as above. It takes no picture itself: only you can.

A capture it cannot use is refused with the reason, and the picture is waited for again: a dragged rectangle, no marks, one theme only, a capture from another repository than the page's, or any refusal above. A capture of another picture of the run is kept for that picture's turn. Press Ctrl+C to stop; the pictures not taken stay as they are. `--stage <dir>` and `--events` make it a run of [`shot_review.mjs`](#shot-review), as they do [`shoot_docs.mjs`](#shoot-docs), and `--against` compares with another revision than `HEAD`. They apply to named captures as well, each capture a job of the run.

With either form, a run that would write under `docs` is a run of the review session, as a [`shoot_docs.mjs`](#shoot-docs) run is.

Exit codes: **0** every capture was written, or left the pictures as they are; **1** a capture was refused or could not be drawn; **2** the tool could not run: a refused command line, or a capture that cannot be read.

## chrome_try.mjs
{: #chrome-try }

    node scripts/svgshot/chrome_try.mjs --url <address> --capture-dir <dir> [--out <path> | --shot <name>] [--follow <name>] [--drag x,y,x,y | --os-drag x,y,x,y] [--scroll N] [--width N] [--scale N] [--mask find=show]... [--window <png>]

Takes a public page through the [Chrome extension](#svgshot-extension) with no person there, which shows that the extension still loads and works after a change to it or to `scripts/svgshot/capture.mjs`. It loads a copy of the extension into Puppeteer's Chrome for Testing, on a private desktop, with a fresh profile, so it is signed in to nothing, and it presses the side panel's buttons as a person would. It saves the capture into `--capture-dir`, for [`chromeshot.mjs`](#chromeshot) with `--out` set to a folder of your own, and then checks that the page is as it found it. It needs the network and `tbbroker`, and is outside every gate.

`--url` is the page, and `--out` the picture's path under `docs`, or `--shot` the name of one of the six pictures, with its marks. `--follow` first tells the panel that a picture is next, as [`chromeshot.mjs --take`](#chromeshot) does, and fails unless it chooses it. It presses **Whole viewport** unless `--drag` gives a rectangle to drag over, in the window's CSS pixels, or `--os-drag` gives one in the device pixels of the Chrome window's client area, sent as Windows' own mouse messages, the path a person's mouse takes. `--scroll` scrolls the page down first, and `--width` fills in **Page width**. `--scale` is the display's scale, 1 by default, so that `--scale 1.5` tries a display at 150%. `--mask` adds a private word and its stand-in, and may be given again. `--window` writes a picture of the Chrome window during the capture.

Exit codes: **0** the capture was saved and the page is as it was found; **1** the panel reported a failure, or the page was not put back; **2** the tool could not run.

## shot_review.mjs
{: #shot-review }

    node scripts/shot_review.mjs [--port N] [--retake <regex> | --replay <regex> | --browser <regex>] [--jobs N] [--ide <twinBASIC.exe>] [--captures <dir>] [--extension <dir>] [--no-open]
    node scripts/shot_review.mjs --archived <id> [--port N]

Reviews what [`shoot_docs.mjs`](#shoot-docs) and [`replay.mjs`](#replay) decided about each picture, in a browser. Both decide with fixed limits: whether a capture differs from the picture enough to be written, and whether an SVG is close enough to its PNG. No limit is right for every picture. A caret or a clock in a large window can count as a change, and a word missing from a large SVG can be within its bar. This tool shows each decision beside the pictures it was made on, and lets a person decide otherwise. It also starts and stops the runs, and commits the result.

It serves its pages at `http://127.0.0.1:4180/`, on the loopback address only; `--port` chooses another port. Open that address in a browser while the tool runs, and press Ctrl+C in its terminal to close it.

The tool works in a *session*: a folder in `.shot-review` at the repository's root, which git ignores, since what it holds can show the Windows user name. A session's *baseline* is the commit its pictures are compared with: `HEAD` when the session was made. Closing the tool loses nothing, and the next start opens the same session. Only one tool at a time holds it.

**The overview** (`/`) shows every picture the session's runs took or drew, as cards in groups: in progress, needs a look, changed (most changed first), only noise, changed outside the runs, unchanged, and added, deleted or failed. *Needs a look* holds the pictures whose decision a person should check, chosen from the regions of the picture that changed: a capture taken although only a fringe or a caret changed, or only a word or two; a capture kept as noise although a block of it changed; an SVG accepted although a part of it is missing, or refused for a fringe alone. *Changed outside the runs* holds the pictures under `docs` whose PNG or SVG differs from the baseline although no run of the session wrote it, such as a retake from a terminal or an edit, whether a run reported the picture or not. A picture's page there shows what changed, the SVG at the baseline beside the file's, and offers **Keep it as it is** or **Put back the baseline's**; the commit waits until each such picture is one or the other. Each card shows a chip for each decision, why the picture needs a look, and its allowances. Filters show only the pictures that need a look, those with an allowance or a decision (*Overridden*), or those with no SVG. **Resume at** goes back to where the review of *Needs a look* was left.

**All pictures** (`/all`) shows every picture `shoot_docs.mjs` takes (the table that [`shoot_docs.mjs --list`](#shoot-docs) prints) and the six of the [Chrome extension](#svgshot-extension), as the working folder has it, whatever any session did. So it is the page to open after a commit, when the overview of the new session is empty. Each card shows the picture's PNG and whether it has an SVG, the build `test/shots/manifest.json` records for it, and its allowances. Its groups are the pictures with no SVG that are of a program's window, the other pictures with no SVG, those the table names that are not under `docs`, those with an allowance or a decision, those with no automated capture, and those with an SVG. A picture with no SVG says why: a program's window, or what the newest verdict of this session or of an archived one said, such as an SVG refused for how far it was off its PNG, with the run and session it is from. When no verdict says, the card says so. **Judge their SVGs again from their bundles** replays the SVGs of the pictures with no SVG that have a bundle, with `--recheck`. A card opens the picture's page of verdicts when the session has one, and otherwise a page that shows the picture at the baseline, the file and its SVG, with **Retake this picture** and **Replay its SVG**. *No automated capture* holds every other image under `docs`, such as a picture replaced by hand, to look at: no run can retake or judge one, so its page shows the file, and the picture at the baseline when that differs. What a script makes (a diagram's SVG, the build's chart, a video's poster frame) and the favicon are not listed.

**A picture's page** compares the picture at the baseline with the new capture: side by side, by a swipe, by blinking between them, and as a difference map, with the SVG against its PNG and its own map. Below them, each region that changed is cropped and enlarged. The page's choices:

- **Keep the old picture** or **Take the new capture**, and **Accept the SVG** or **No SVG**. A decision is kept in `test/shots/manifest.json` for exactly the bytes it was made on. A later capture with other bytes is judged by the rule again, and goes back to *Needs a look*.
- **Allowances**: the picture's own noise rule (the grey levels and the share of pixels) and its SVG's own bar, each with rectangles left out of the comparison. Drag on the picture to draw a rectangle. An allowance lasts, across retakes, until it is removed.
- **Back to the tool's verdicts** removes the picture's decisions.
- **Retake this picture** and **Replay its SVG** start a run of the one picture. A picture only your browser can take has **Retake in the browser** instead.

Each change judges the picture again at once and writes the result under `docs`. The keys J and K move to the next and the previous picture.

**The runs page** (`/runs`) starts a retake (`shoot_docs.mjs --svg`, with an IDE chosen from the installs found), a replay (`replay.mjs`) or a clean-up (`shoot_docs.mjs --cleanup`, whose list of pictures is shown first) of the pictures matching a pattern or of those selected on the overview. One run runs at a time. Each run shows the command line it is the same as, its progress by setup, and its log, and **Stop** ends a retake or a replay as its own end would: its IDEs end and the registry is put back. **Kill** ends its process at once, which skips that, and is offered only after a stop. `--retake <regex>` or `--replay <regex>` starts a run as the tool opens; `--jobs` and `--ide` are its options.

**A browser retake** is for the six pictures of the [Chrome extension](#svgshot-extension), which need your own sign-in, and is what any retake of them starts: their page's button, a selection on the overview, or the form of its own on the runs page. It runs [`chromeshot.mjs --take`](#chromeshot). The tool brings the extension up to date on disk, opens the picture's page in your default browser, and shows on the runs page what to do there: the picture's state, what to do about the extension if anything, a link to open the page again, and why the last capture was refused. Set the page up and press **Whole viewport** in the panel. The tool takes in the capture when the browser saves it, judges it as it does any other, and goes on to the next picture. **Stop** ends the wait, and leaves the pictures not taken as they are. `--browser` starts one as the tool opens, `--captures` names the folder your browser saves to when it is not `svgshot` in Windows' Downloads folder, `--extension` the extension's folder, and `--no-open` opens no page. A retake of these and of the IDE's pictures are runs of their own.

A run of [`shoot_docs.mjs`](#shoot-docs), [`replay.mjs`](#replay) or [`chromeshot.mjs`](#chromeshot) typed in a terminal while the tool is open is handed to the tool, shows on its runs page with the others, and is followed in that terminal, whose Ctrl+C stops it; with the tool closed it opens the session itself, and the tool shows it the next time. A retake or a replay runs with `--stage` and `--events`, so it writes nothing under `docs` itself. The tool applies each decision under `docs` as it arrives, and a picture can be reviewed while the run goes on. A retake and a clean-up compare with the session's baseline (`--against`), whatever `HEAD` is. When `HEAD` moves under the session, the overview says so and offers to move the session to it.

**The commit page** (`/commit`) commits the session's own files and nothing else: the PNGs and SVGs its runs reported that git reports changed, the pictures changed outside the runs that a review kept, and `test/shots/manifest.json`. It counts them, lists them, and lists the working folder's other changes as left out. While a picture changed outside the runs is neither kept nor put back, the page lists it and the commit waits, so that a commit from the tool leaves no picture under `docs` different from `HEAD`. The message is one line by default, such as *Screenshots retaken on BETA 1034: 1 taken by review*, can be edited, and **Back to the default message** puts it back. The commit runs the repository's hooks, which take a few seconds. Meanwhile the tool goes on serving its pages, which say that the commit is under way, also when fetched again or opened in another tab, and it refuses any change and any run until the commit has ended. Ctrl+C waits for a commit under way to end before it closes the tool. The commit is refused while a run runs, or while `HEAD` is not the baseline. A commit closes the session: it is archived as `.shot-review/archive/<id>`, `<id>` the commit's short hash, and the tool goes on with the next session, whose baseline is the new commit. `--archived <id>` opens an archived session again, read-only, beside the open one on another `--port`.

Exit codes: **0** the tool was closed; **2** the tool could not run: a refused command line, the port in use, the session held by another tool, no archived session of that id, no git working folder, or a crash.

## imagestrip
{: #imagestrip }

    imagestrip_win32.exe <input> <output>

A twinBASIC console program, and one of two under `scripts/` that are not Node or Python (the other is the twinBASIC edition of [`impexp`](/Documentation/Development/Tools-Compiler.md#impexp)). It writes a copy of a CSS file or an SVG file in which every image embedded as a `data:` URI keeps its pixels and any notice of whose it is, and nothing else. An SVG file also loses what only its editor needs, and so does an SVG embedded in either, whose own images are stripped in turn, at any depth. A file whose name ends in `.svg` is read as an SVG, any other as CSS.

It is for the twinBASIC IDE's own stylesheets, `styles.css`, `formDesigner.css` and the others in an install's `ide` folder, and for the twinBASIC developers to run in their build, which has twinBASIC and need not have Node. The icons in those stylesheets carry their editors' metadata (GIMP's EXIF, IPTC and XMP profiles, CorelDRAW's and Illustrator's comments) around a few hundred bytes of pixels. One icon, a lock from fileformat.info, has a CC BY-NC-SA attribution that must stay with it.

The program does to a file what `stripFile` in `scripts/lib/compact-image.mjs` does, and [its tests](/Documentation/Development/Tools-Toolchain-Tests.md#compact-image-test) check the program's output against that function byte for byte. Each image is stripped as `compactImage`, in the same module, strips it:

- **A PNG** keeps the chunks a browser draws from (`IHDR`, `PLTE`, `tRNS`, `IDAT` and `IEND`, and `acTL`, `fcTL` and `fdAT` for an animated PNG) and its colour-space chunks (`iCCP`, `sRGB`, `gAMA`, `cHRM`, `sBIT`, `cICP`, `mDCV` and `cLLI`). The colour-space chunks go when all they say is that the picture is sRGB, which a browser assumes for a PNG that says nothing: an ICC profile with sRGB's colourants and tone curves (GIMP puts its own in every PNG it saves), or, with no profile, an `sRGB` chunk. `gAMA` and `cHRM` go with them. Any other profile stays, and so does every colour chunk beside a `cICP`. The chunks that stay are copied byte for byte, so the pixels do not change.
- **A JPEG** keeps the segments that decode it: the frame, the tables, JFIF, the ICC profile and Adobe's colour transform. EXIF, XMP, Photoshop's IPTC, comments and other applications' segments go. Everything from the start of the scan is copied unchanged.
- **A GIF** loses its comments and its XMP packet. Every other block stays, an animation's included.
- **An SVG** loses its XML declaration, a DOCTYPE that declares nothing, its comments and its `<metadata>` elements. A DOCTYPE that declares entities stays, and so does a `<?xml-stylesheet?>` instruction, which styles the picture. The inside of a CDATA section is left as it is.

In every format, a notice of whose the picture is and on what terms stays, byte for byte:

- a PNG text chunk whose keyword is `Title`, `Author`, `Description`, `Source`, `Copyright` or `Disclaimer`, or names a licence or rights;
- a comment that says "copyright", "licence", "(c)" or "all rights reserved";
- an EXIF, IPTC or XMP profile that gives a value to an author or a rights field.

An EXIF that turns the picture stays too. A chunk or a profile the program cannot read stays, because dropping a notice is the mistake to avoid.

**An image is known by its bytes, not by its label**, and is labelled with what it is. A JPEG labelled `image/png` comes out labelled `image/jpeg`, and the change is reported on standard error with its line. Only the media type is replaced; a parameter after it stays. A BMP is labelled `image/bmp` and otherwise left as it is. A payload labelled as a PNG, a JPEG, a GIF or a BMP that is none of the four is left unchanged and reported. Anything else, such as a font or a WebP image, is left unchanged without a report.

**A `data:` URI is read where it follows a quote or `url(`.** Its header runs from `data:` to the first comma. Its text runs to the quote just before `data:`, or to the `)` of a `url(` before it, with white space allowed between `url(` and `data:`. A `data:` anywhere else is left alone. Base64 is read as a browser reads it, with the white space inside it ignored, so the line breaks Illustrator writes into a PNG inside an SVG are no obstacle.

- In CSS, the text's escapes are undone before it is read.
- In an SVG, character and entity references such as `&quot;` and `&#10;` are undone, but not in a CDATA section, where they are text. A quote written as a reference, as in `url(&quot;data:...&quot;)` in a `style` attribute, is ended only by a quote written as one.
- An SVG's own CSS, the text of a `<style>` element and the value of a `style` attribute, is read as CSS: references are undone first, then escapes. In a `style` attribute, a line break written as itself is read as a space, as XML reads it, while `&#10;` stays a line break.

**A style sheet in a `data:text/css` URI is stripped as a CSS file is**, wherever it is: in an `@import` of a CSS file or in an SVG's `<?xml-stylesheet?>`. It is not counted as an image.

**An image keeps the encoding it has, and so does a style sheet.** Base64 is written again only when what it holds changed, and then without white space. In an SVG or style sheet written as text, percent-encoded or not and with CSS escapes such as `\'` or `\3C `, the characters it loses are cut out as the file has them, and any it gains (base64) are put in as they are. The rest is unchanged. Base64 that cannot be read, and an SVG or style sheet that cannot be read --- a `%` that starts no escape, or, for an SVG, bytes that are not UTF-8 --- are left unchanged and reported.

An image with nothing to strip keeps its original text, so a second run changes nothing. Everything outside the images is copied unchanged. The output may be the input file.

The program differs from `compactImage` in two ways. `compactImage` converts a BMP to a PNG; the program only relabels it, as it has no PNG encoder. And `compactImage` writes every SVG as percent-encoded text, where the program keeps the SVG's encoding.

The program is `scripts/imagestrip/src/`, an exported project tree, and `scripts/imagestrip/imagestrip.twinproj`, the project file packed from it, which opens in the IDE. Both are checked out byte for byte (`.gitattributes`), so the two agree in every checkout. After a change to `src/`, pack it again:

    node scripts/impexp.mjs import scripts/imagestrip/imagestrip.twinproj scripts/imagestrip/src --overwrite

Build it in the IDE, which writes `Build\imagestrip_win32.exe` beside the project file (git ignores it), or with [`tbbuild.mjs`](/Documentation/Development/Tools-Compiler.md#tbbuild), which builds in a private folder and prints the path:

    node scripts/tbbuild.mjs scripts/imagestrip/imagestrip.twinproj --build

It prints one summary line to standard output, naming the input as it was given, and one line for each report to standard error. For a style sheet `site.css` that embeds 140 images, one of them a PNG labelled `/png`:

    site.css: 140 images, 90 stripped, 1 relabelled; 1042091 -> 870074 bytes
    site.css:2947: labelled /png, but is a PNG; now labelled image/png

The images counted include an SVG file itself and each image inside another. *Stripped* counts those that lost something of their own, and *relabelled* those whose label changed. A report on an image inside another names the line of the outermost `data:` URI around it. Both streams can be redirected, as [Writing a command-line tool](/Features/Project-Configuration/Project-Types.md#writing-a-command-line-tool-output-exit-code-and-arguments) describes. The program has no `--help`: run without arguments, it prints its usage to standard error and exits 2.

No gate builds the program, so `test.bat` and CI skip the half of [`compact-image.test.mjs`](/Documentation/Development/Tools-Toolchain-Tests.md#compact-image-test) that runs it. After a change to `src/`, build it and run that half by hand, with `IMAGESTRIP_EXE` naming the exe:

    set IMAGESTRIP_EXE=<path of imagestrip_win32.exe>
    node --test test/compact-image.test.mjs

Its unit tests are in twinBASIC, beside its code in `src/Sources/`: the `[TestFixture]` modules `PngTests`, `ColourTests`, `JpegGifTests`, `SvgTests`, `FileTests` and `InflateTests`, whose images `TestImages` builds byte by byte. They call the program's code directly and check it with the Assert package, case for case as the module tests of `compact-image.test.mjs` check `compactImage` and `stripFile`. They also check that `Inflate` reads the stored, fixed and dynamic blocks zlib writes. [`tbrun.mjs`](/Documentation/Development/Tools-Compiler.md#tbrun) runs them in the compiler's test mode and prints PASS or FAIL for each:

    node scripts/tbrun.mjs scripts/imagestrip/src --tests

Exit codes: **0** the output was written, with or without reports; **1** a file that cannot be read or written: an input that does not exist or is a folder, an output whose folder does not exist or that is itself a folder, or a write that is refused; **2** a command line without exactly two arguments.
