Story: VSNote runs Markii's Lua scripts inside a dedicated Web Worker, never on the main thread, with a watchdog that can terminate the worker if a script hangs. Wiring pack modules and the value store into that worker surfaced two friction points in the scripting API's shape.
What went wrong: PackModuleResolver is a synchronous interface, but the code that needs to consult it, ScriptView/CacheProvider, is async by nature (pack modules can live in an .mkz bundle behind a fetch). We worked around this by snapshotting every pack module into the worker up front, before the script runs, so the resolver inside the worker never needs to await anything. That means a host cannot lazily resolve pack modules; everything a script might touch has to be materialized ahead of time.
Separately, renderMark's ValueStore and vault parameters are passed positionally, and that positional contract is documented nowhere outside the .d.ts file. We only discovered the right argument order and meaning by reading the type declaration and, in one case, by trial and error against a failing render. Threading the value store through our own render call took longer than it should have for what is, functionally, two extra arguments.
Suggestion: allow PackModuleResolver to return a Promise so a host can resolve pack modules lazily instead of snapshotting everything up front. Separately, document the ValueStore/vault parameters in docs/ (not just the .d.ts), and consider moving them into an options object so future additions do not need another positional slot.
Story: VSNote runs Markii's Lua scripts inside a dedicated Web Worker, never on the main thread, with a watchdog that can terminate the worker if a script hangs. Wiring pack modules and the value store into that worker surfaced two friction points in the scripting API's shape.
What went wrong:
PackModuleResolveris a synchronous interface, but the code that needs to consult it,ScriptView/CacheProvider, is async by nature (pack modules can live in an.mkzbundle behind a fetch). We worked around this by snapshotting every pack module into the worker up front, before the script runs, so the resolver inside the worker never needs to await anything. That means a host cannot lazily resolve pack modules; everything a script might touch has to be materialized ahead of time.Separately,
renderMark'sValueStoreand vault parameters are passed positionally, and that positional contract is documented nowhere outside the.d.tsfile. We only discovered the right argument order and meaning by reading the type declaration and, in one case, by trial and error against a failing render. Threading the value store through our own render call took longer than it should have for what is, functionally, two extra arguments.Suggestion: allow
PackModuleResolverto return a Promise so a host can resolve pack modules lazily instead of snapshotting everything up front. Separately, document theValueStore/vault parameters indocs/(not just the.d.ts), and consider moving them into an options object so future additions do not need another positional slot.