Ses initial draft review

[tyg]

No description provided.

[dckc]

I'm new to reviewing docs. The "files changed" view here has lots of distracting markup and doesn't make clear what context is available to the reader.

CONTRIBUTING.md says

4. Check your changed docs in a local copy of the repo and local documentation server.

but I don't see details on how to start a local documentation server.

The yarn.lock suggests yarn install should get dependencies, and it runs without error, but then the conventional yarn start loses with error Command "start" not found. Inspecting package.json suggests yarn docs:dev but that fails with vuepress: not found.

Suggestions?

[kriskowal]

This review covers all of the **tyg blocks I could find. Please as always let me know if I missed a question!

[kriskowal]

(With regret, I can’t propose a suggestion since the suggestion contains code fences. So here’s my suggestion inline.)

On Node.js and in web browsers, use the SES shim to transform an ordinary JavaScript environment into a SES environment.

On Node.js you can import or require ses in either CommonJS or ECMAScript modules, then call lockdown. This is a “shim”, meaning that it mutates the environment in place such that any code running after the shim can assume that it’s running in a SES environment, one that includes the globals lockdown, harden, Compartment, and so on.

require("ses");
lockdown();

import 'ses';
lockdown();

To ensure that a module gets run in a SES environment, wrap the text above in a ses-lockdown.js module and import that.

import './non-ses-code-before-lockdown.js';
import './ses-lockdown.js'; // calls lockdown.
import './ses-code-after-lockdown.js';

To use SES as a script on the web, use the UMD build.

<script src="node_modules/ses/dist/ses.umd.min.js">

The full SES environment includes a module system that requires a translating compiler. To use the much thinner version of SES that just provides an evaluator Compartment, use the ses/lockdown layer. It is much smaller and useful especially if all client code gets bundled as a script out-of-band.

import 'ses/lockdown';

<script src="node_modules/ses/dist/lockdown.umd.min.js"></script>