`#strict on` and `//@strict on` no longer end the run as unsupported. They
turn on the checks the dollar-object help page gives for `$.strict`
(https://extendscript.docsforadobe.dev/extendscript-tools-features/dollar-object/):
an assignment to a read-only property throws a TypeError, and so does a new
property on an object that takes none.
VectorCraft's own rules: a getter-only property counts as read-only; the
objects that take no new properties are the non-extensible ones
(preventExtensions, seal, freeze, and the frozen vc and $ objects); the last
`#strict` line of the script and its includes sets the whole run, and runs
without one are unchanged; eval and Function take the checks of the code
that compiles them; a file $.evalFile runs keeps its own line's checks for
its code and functions, or takes the caller's without one. The rest of ES5
strict mode stays with 'use strict'.
The js crate carries the setting per compiled source
(Realm::set_strict_writes, and a strict_writes callback on
HostItem::Evaluator), and applies it only to property assignments.
Before a script runs, `script.run` reads its preprocessor lines (`#` or
`//@` at the start of a line, outside strings and comments):
- `#include` and `//@include` put another file's text in place of the
line, looked for beside the including file, then in each
`#includepath` folder, then in each `JSINCLUDE` folder. A later
`#includepath` replaces the list.
- `#script` names the run unless `name` is given; `#target` takes any
value; `#strict off` is taken. `#strict on`, `#targetengine` and
`#engine` are refused as unsupported, and any other `#name` as
unknown.
`$.evalFile(path, timeout?)` runs a file in the same global environment
and returns its last value, `$.fileName` is the file being run and
`$.includePath` the include folders.
A script run from a file reads these files only in its folder and the
folders below it. Paths with a `..` name, links or junctions that lead
out, device names, streams and network paths are refused; a script
given as text reads none. A run reads at most 64 files 16 levels deep,
32 MiB of source in all and 1,024 paths looked up. An error in an
included or evaluated file is reported at that file's line and column,
and the report's new `file` field names it.
Docs: docs/mcp.md (script.run, Script Console), docs/target-app-parity.md.
A script renamed to its whole file name could take the label another
script kept, as with tidy.js, tidy.jsx and tidy.js.js in one folder.
The rename now repeats until no label is shared. A folder entry whose
type cannot be read now marks the listing as incomplete.
File › Scripts now lists the .js and .jsx files of the Scripts folder next
to the preferences, each named after its file without the extension, with
each subfolder as a submenu, above Check Script… and Other Script…. The
help page describes this listing:
https://helpx.adobe.com/illustrator/desktop/automate-visualize-data/automate-actions/install-and-run-scripts.html
Choosing a listed script runs it through script.run without the warning
Other Script… shows. script.listInstalled returns the same listing, and
ui.runInstalledScript {path} runs one entry.
VectorCraft's own rules: the folder is read off the UI thread when the
app starts, when its window becomes active and when the File menu of the
window's menu bar opens; only names are read; links, junctions, hidden
and system entries are left out and checked again before a run; one read
stops at 2,048 entries, 512 scripts, 128 subfolders, 4 levels or 250 ms
and the menu then notes that some scripts were not listed. Under an
automation read root, script.listInstalled and ui.menu.list leave out a
folder outside the root.
#1183 (LloydNicholson) also proposed a Scripts menu listing a folder.
Scripts write to a new Script Console with $.write(...values) and
$.writeln(...values), each value as String(value) gives it. vc.log
entries, a run's uncaught error as name:line:column: message, and a
start, end and report line for each run go there too. The report line
gives the run's time, host calls and slowest commands.
- The console keeps at most 2,048 lines and 1 MiB of text, dropping the
oldest and counting what it dropped. A line is cut at 4,096 bytes and
a script's name at 256 bytes, with a count of cut lines. Line feeds,
carriage returns and CRLF break lines; other control characters show
as Unicode Control Pictures.
- script.run's result and scriptReport gain runTimeMs, timingAvailable,
hostCallCounts, slowestCommands and the run's own console. A failed
run's report has them too.
- script.console and script.console.clear read and empty the console;
ui.copyScriptConsole {first?, last?} copies lines as the panel shows
them.
- The panel lays out only the rows in view, selects with click and
Shift-click, and has Clear, Copy Selected and Copy All. Output goes on
while it is closed, and Clear works during a run.
Docs: docs/mcp.md, docs/gaps.md, docs/roadmap.md,
docs/target-app-parity.md.
`Session::history_budget` (default `default_history_budget()`) caps the
memory the undo steps of all open documents keep together. After each
command, tool edit, interaction commit, direct edit, framed script run
and closed undo group, `Session::trim_histories` drops the oldest steps
of any document first, undo steps before redo steps. Each document keeps
its last eight undo steps and next eight redo steps, and a held history
keeps all of its steps. While a script runs or an undo group is open,
no steps are dropped, so a canceled group leaves the other documents'
steps in place. Closing a document frees its share. The steps are not
counted again while neither the budget nor any history changed. Each
document's own `byte_budget` stays as its ceiling.
A script.run that a control request started in the app's frames was
advanced by later frames, which run unconfined, so its vc.run file
commands could read and write outside the caller's automation roots.
The job now keeps the file-access scope of its script.run and runs
each slice in it, as background opening and the folder walker do.
Each command a script runs keeps a savepoint of the state it may need
to put back if it fails. The savepoint cloned every open document's
whole undo history, so a script that made N edits did O(N^2) work.
- The savepoint now clones each document's state without its history
and keeps a mark: the newest undo and redo steps and the serials of
the steps under them. Until the command ends, the history trims no
step, and a new step sets the redo steps aside instead of dropping
them. A failed command truncates both stacks back to the mark.
- file.close, file.closeAll, document.close and file.revert still keep
a whole copy, since they remove the history or the document.
- When a failed command removed or changed a step under the newest
one, the history cannot be put back exactly, and the run stops with
an error; its rollback restores the documents as they were before
the run.
- run_guarded no longer copies the histories during a script's run,
and a committed run moves the histories from before it back instead
of copying them.
- Symbol editing mode shares its saved redo steps between copies of a
document's state.
- A script cannot run edit.clearHistory. A run keeps each document's
undo steps from before it, so the command reported a clear that the
commit then undid.
A document a script opens now counts the art in its graph designs and in
the original of the pattern being edited toward the growth allowance.
`Document::art_roots` and `art_roots_mut` list every tree of a document's
art; `any_node`, `edit_nodes_where` and the script's object count use them.
`script.run` checks the depth of `args` without recursion before it copies
or writes them out, so `args` nested 10,000 levels deep is refused with the
place it went past 64 levels instead of overflowing the stack.
New tests: graph-design art and the growth allowance, `args` nested 10,000
levels deep from a script (a RangeError) and from a caller, `run --cmd
script.run` on the command line with a report and with a thrown error, and
a property test that sends arbitrary source through `script.run`.
view.capsLock joins the state a run puts back when it fails or is
stopped. A finished run keeps the state it set, and keeps the state the
app reported during the run when the script did not change it. The
pointer over the canvas is refreshed when a run's end changes Caps Lock.
A document that document.open or file.new adds during a run counts whole
toward the growth allowance: every object in its layers, symbols and
patterns, opacity masks included, and its document data.
File › Scripts › Other Script… picks a .js or .jsx file, shows a warning
that can be turned off in Preferences › General, and runs the script
against the open documents through the `vc` object. The new
`script.run` and `script.stop` commands run and stop a script over MCP.
- A run is one transaction. Each document it changed gets one undo step
named Run Script. An uncaught error, a limit or a stop puts every
document, the paint, the clipboard, menu state and preferences back.
- A command that fails inside a run, or whose result is too large to
reach the script, is undone and throws an error the script can catch.
- Files a command wrote stay on disk and the report names them, also
when the run is stopped from the quit question.
- While a script runs, other commands that change anything fail with a
busy error; MCP reports it as JSON-RPC error -32003.
- In the app the run advances one slice per frame with a Stop button in
the status bar. A run that adds a great many objects asks whether to
continue; Stop and Escape end it.
- Commands that change state outside the documents, such as prefs.*,
plugin.* and file.place.queue, are refused to scripts.
Docs: docs/mcp.md, docs/gaps.md, docs/roadmap.md,
docs/target-app-parity.md.
dotCooCoo