Skip to content

Conversation

@younes-io
Copy link
Collaborator

@younes-io younes-io commented Nov 20, 2025

Related to #441

  • Embed Spectacle inside the VS Code extension via the tlaSpectacle.open command and a CSP-safe webview that injects the active editor’s spec into the bundled UI while staying fully offline.
  • Add tools/fetch-spectacle.js, a deterministic bundling script that clones Spectacle, whitelists essential assets, vendors JetBrains Mono & Source Code Pro fonts, strips analytics/external fonts, rewrites worker/resource paths, injects a history guard plus router-disable flag, implements TLC Assert, and emits a SHA256 manifest so reruns reproduce the bundle exactly.
  • Trim the shipped payload to ~9.4 MB by pruning bootstrap icons, animation demos, and other optional assets; animation remains intentionally omitted to stay within marketplace and offline constraints.
  • Extend coverage with a unit test for buildSpectacleHtml and Playwright smoke tests that serve the bundle over an internal HTTP server, stub acquireVsCodeApi, verify Spectacle renders, and run a PlusCal trace (squares.tla) to prove the injected Assert works.

Key Decisions

  1. Offline-first fetch script: automate all asset pruning/patching so the bundle stays deterministic, offline, and size-capped whenever Spectacle is refreshed.
  2. History/router shim: VS Code webviews block history.replaceState/pushState, so Spectacle now guards those calls and can run with a router-disable mode.
  3. Animation exclusion: optional animation demos pull remote assets and add weight; removing them keeps the extension lean and compliant while still covering core spec exploration.
  4. Testing: combine Mocha HTML tests with new Playwright smoke tests to ensure the trimmed bundle loads through VS Code messaging and evaluates PlusCal specs without errors.

@lemmy
Copy link
Member

lemmy commented Nov 21, 2025

/cc @will62794 ^^

@lemmy
Copy link
Member

lemmy commented Dec 4, 2025

There are two binary files (fonts) in this PR. Could you please specify the license for these fonts? Are these under permissive licenses?

@lemmy
Copy link
Member

lemmy commented Dec 4, 2025

Given the existence of tools/fetch-spectacle.js, why not download Spectacle at extension build time (Github Action workflow) instead of adding it to our git repo?

);
}

const routerOriginal = ' // m.mount(root, App)\n m.route(root, "/home",\n {\n "/home": App,\n "/eval_debug_graph": EvalDebugGraph,\n });';
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this replacement robust against upstream Spectacle changing the value of routeOriginal?

fs.writeFileSync(stylePath, style);
}

function patchAppJs(destDir) {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These patches are hard to read. Have you considered generating .diff files that fetch-spectacle.js could apply using the patch tool (this is how Debian et al. .debs modify upstream packages)? That approach would improve robustness and provide proper error reporting.

@lemmy
Copy link
Member

lemmy commented Dec 4, 2025

Zooming out from the question of how to patch fetch-spectacle.js, could the required changes be upstreamed and integrated directly into Spectacle?

@lemmy lemmy added the enhancement New feature or request label Dec 4, 2025
fs.writeFileSync(appPath, code);
}

function patchEvalJs(destDir) {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Patching Spectacle's evaluator to support TLC!Assert should instead be done in dedicated upstream PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Development

Successfully merging this pull request may close these issues.

2 participants