Repository navigation
[experimental] export: the page's script is a module script - #12761
josephfarina wants to merge 1 commit into
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
AI review status for this pull request.
|
There was a problem hiding this comment.
Changes requested. The move to a module script fits the first-paint goal, but two things need fixing before it can land.
packages/cli/foundation/render/render-page.mjs:2166now writes the esbuild IIFE as a module script, whileclient-bundle.mjs:722still checks it with a classicvm.Scriptparse, so a page whose bundled CommonJS dependency uses awithstatement or assigns an undeclared name renders with no error or warning and then fails in Chromium (a SyntaxError for the whole script, or a ReferenceError on the first click), where the base file works; build or check the script as module code (for example esbuildformat: 'esm'or asourceType: 'module'parse), and keep the classic script or document strict mode for non-strict CommonJS input.- The changeset's "The page is ready as soon as before" and the description's "so it runs the same in strict module mode" claim more than the evidence shows (your own data has one page more than 100 ms slower to interactive, and the pages above never become interactive), so narrow both to what holds.
Smaller points: .github/scripts/pages-landing.test.mjs opens a page with no module script, so the pageDom switch there only adds pretendToBeVisual and can be reverted, and a <script type="module"> line in the docsite landing-preview test fixture would pin the new strip regex.
Claims and files checked
Review mode: full; reason: no-earlier-review
Claims:
- The exported page's script is a module script: verified,
render-page.mjs:2166. - It runs once the file is parsed, so the browser paints before the script draws: consistent with how browsers run inline module scripts; timing not independently measured.
- A small page paints about 200 ms sooner on a slow phone: the author's measurement, not independently repeated.
- The page is ready as soon as before: false as stated; the description's own data has one page more than 100 ms slower, and a page whose bundled dependency uses
withor assigns an undeclared name never becomes ready in Chromium. - Before, a classic script at the end of the body ran before the first paint: verified, the base writes a plain
<script>last in the body. - The file is otherwise the same, with no option, result field, type or render format change: verified,
render-page.mjs:2249-2283; each file grows by the 14 bytes of the attribute. - A frame that blocks scripts still shows the markup, and the source block, its note and the way back are unchanged: verified,
render.notes.test.mjs:153-157and the round-trip tests pass. - The script uses no current-script lookup or top-level
this, so it runs the same in strict module mode: true for the render's own prelude and image sinks, false for bundled dependencies, as the two Chromium failures above show. - Running the mount on a later event or timer was rejected for slower readiness: design rationale, not independently measured.
- Phone and desktop timings and unchanged file sizes: the author's measurements, not independently repeated.
- The script runs from a file and in a scripts-only sandboxed frame with a script policy, and runs nothing in a fully sandboxed frame: not independently checked in those modes; the failures above were checked in Chromium.
- The 788 templates render, mount, round-trip and log the same messages: not independently repeated; 788 is 58 page and 730 block templates.
- The listed tests, lint and the changeset check pass: verified for the five changed test files (316 tests), eslint on the changed files and the changeset check.
- The test helper runs inline module scripts after parsing, in strict mode, with no top-level
this, reporting a throw as the window's error event, as a browser does: mostly; under JSDOM an assignment to an undeclared name does not throw, unlike Chromium. - Stacked on #12752: verified, its head is this pull request's base.
Files:
.changeset/render-module-script.md: finding (overclaims readiness)..github/scripts/pages-landing.test.mjs: non-blocking note (helper switch has no effect beyondpretendToBeVisual).apps/docsite/scripts/generate-landing-template-previews.mjs: clear (non-blocking: no fixture for the new regex).packages/cli/api/render/render.interactive.test.mjs: clear.packages/cli/api/render/render.notes.test.mjs: clear.packages/cli/api/render/render.test.mjs: clear.packages/cli/foundation/render/remote-images.test.mjs: clear.packages/cli/foundation/render/render-page.mjs: finding (module script checked as a classic script).packages/cli/test-utils/page-dom.mjs: clear (its JSDOM limit is noted under the first finding).
499b325 to
dc1c34f
Compare
28a9f3e to
d86e7a3
Compare
There was a problem hiding this comment.
Changes requested. The strict-mode gate now keeps a classic script for CommonJS packages that need sloppy mode, which fixes the earlier breakage, but two things need fixing before this can land.
packages/cli/foundation/render/client-bundle.mjs:653(let module = false;) fails the repository'sno-useless-assignmentESLint rule, because every path through thecatchthrows, sopnpm lintand the Lint check fail; drop the initial value.- The description still says every exported page's script is
<script type="module">and that the script runs the same in strict module mode, but the head keeps a classic script for bundled CommonJS code that does not ask for strict mode (as the new test atrender.interactive.test.mjs:194asserts), so state that condition as the changeset already does.
Smaller points: the gate reads a page's own files by esbuild's astryx-page: name, so a page's own strict CommonJS .js module never gets the module script and the new classic-script test never reaches the directive check, and it skips .ts and .cts files, so a page's own CommonJS TypeScript module that writes an undeclared name loses its controls in Chromium with no warning; reading locatedFile(name) and checking every non-ESM script input would cover both. The comment above runsAsModule says the module parse refuses await as a name, which esbuild.transform with format: 'esm' does not.
Claims and files checked
Review mode: full; reason: rebase
Claims:
- Changeset: an exported page's script is a module script when it runs the same in strict mode: verified for pages whose packages ask for strict mode (Chromium); narrower than stated for a page's own CommonJS files.
- Changeset: the module script runs once the file is parsed, so the browser paints before the script draws: consistent with how browsers run module scripts; timing not measured here.
- Changeset: first paint about 200 ms sooner on the measured pages, with about the same time until the page responds: the author's measurement, not repeated.
- Changeset: a page that bundles a CommonJS package that does not ask for strict mode keeps a classic script: verified for an undeclared write and a
withstatement, in JSDOM and Chromium. - Before, a classic script at the end of the body ran before the first paint: verified, the base writes a plain
<script>last in the body. - The page's script is now a module script and the file is otherwise the same: false as stated; pages with sloppy-mode CommonJS code keep a classic script.
- Experimental export output only, with no option, result field, type or render format change: verified.
- The script tag of an exported page is a module script, with nothing for the caller to decide: false as stated, for the same reason.
- A frame that blocks scripts still shows the markup, and the source block, its note and the way back are unchanged: verified (
render.notes.test.mjs:153, the source-block reader). - The script uses no current-script lookup and no top-level
this, so it runs the same in strict module mode: true for the render's own code, false for bundled code, which is why the head keeps a classic script for some pages. - Running the mount on a later event or a timer was rejected as slower: design rationale, not measured.
- Phone and desktop timings and unchanged file sizes: the author's measurements, not repeated; the tag adds 14 bytes.
- The script runs in three engines from a file and in a scripts-only sandboxed frame, and runs nothing in a fully sandboxed frame: Chromium checked in a same-origin frame only.
- The 788 templates render, mount, round-trip and log the same messages: not repeated.
- The listed tests pass: verified for the four changed render test files (317 tests) and the docsite preview test (29 tests); the rest not run.
- ESLint is clean: false (
client-bundle.mjs:653). - The changeset check is clean: verified; the declaration typecheck was not run.
- The test helper runs inline module scripts after parsing, in strict mode, with no top-level
this, reporting a throw as the window's error event: verified by reading; under JSDOM an undeclared write still succeeds. - Stacked on #12752: verified, its head is this pull request's base.
Files:
.changeset/render-module-script.md: clear.apps/docsite/scripts/generate-landing-template-previews.mjs: clear.apps/docsite/src/__tests__/landing-template-previews.test.ts: clear.packages/cli/api/render/render.interactive.test.mjs: non-blocking (the classic-script test passes through the unreadable-path branch).packages/cli/api/render/render.notes.test.mjs: clear.packages/cli/api/render/render.test.mjs: clear.packages/cli/foundation/render/client-bundle.mjs: finding (ESLint error at line 653); non-blocking (page files read by namespace, TypeScript skipped, module parse weaker than its comment).packages/cli/foundation/render/page-worker.mjs: clear.packages/cli/foundation/render/remote-images.test.mjs: clear.packages/cli/foundation/render/render-page.mjs: clear.packages/cli/test-utils/page-dom.mjs: clear (its JSDOM limit is noted above).
dc1c34f to
6834bf6
Compare
d86e7a3 to
56647bf
Compare
There was a problem hiding this comment.
Changes requested. The strict-mode gate now reads the page's own CommonJS files and the lint error is gone, so one point remains before this can land.
- The description says the script "uses no
document.currentScriptand no top-levelthis, so it runs the same in strict module mode", butrunsAsModule(packages/cli/foundation/render/client-bundle.mjs:936) does not check bundled code forcurrentScript, so a page that bundles a package readingdocument.currentScriptwhile it loads gets a module script, where that value isnull, and in Chromium the page throws and never comes alive; keep the classic script when the bundle containscurrentScript, or limit the sentence to the render's own code.
Smaller point: the classic-script test uses the page's own count.js, so no test covers a node_modules package without the directive, which is the case the changeset names.
Claims and files checked
Review mode: full; reason: rebase
Claims:
- Changeset: an exported page's script is a module script when it runs the same in strict mode: verified for pages whose bundled non-ES files ask for strict mode (Chromium: a strict package and the page's own strict CommonJS
.jsand.tsfiles get a module script and work). - Changeset: the module script runs once the file is parsed, so the browser paints before the script draws: consistent with how browsers run module scripts; timing not measured here.
- Changeset: first paint about 200 ms sooner on the measured pages, with about the same time until the page responds: the author's measurement, not repeated.
- Changeset: a page that bundles a CommonJS package that does not ask for strict mode keeps a classic script: verified in Chromium for a package that writes an undeclared name and one that uses
with; no test in the pull request covers a package. - Before, a classic script at the end of the body ran before the first paint: verified, the base writes a plain
<script>last in the body. - The page's script is now a module script and the file is otherwise the same: verified with the exception the description states below it; on the probe pages the script text is byte-identical to the base's apart from the tag.
- Experimental export output only, with no option, result field, type or render format change: verified.
- The script tag of an exported page is a module script, with nothing for the caller to decide: verified with the same stated exception; no option is added.
- A frame that blocks scripts still shows the markup, and the source block, its note and the way back are unchanged: verified (the source-block reader finds the block by its type;
render.notes.test.mjs:153). - The script uses no current-script lookup and no top-level
this, so it runs the same in strict module mode: false as stated; true for the render's own code, and top-levelthisis the same in both script kinds, but bundled code can read the current script and then fails as a module. - A module script is written only when the module parse accepts the bundle and every non-ES file asks for strict mode, and the docsite previews strip either kind: verified (gate code; Chromium probe;
landing-template-previews.test.ts:184). - Running the mount on a later event or a timer was rejected as slower: design rationale, not measured.
- Phone and desktop timings and unchanged file sizes: the author's measurements, not repeated; on the probe pages the script text is unchanged and the tag adds 14 bytes.
- The script runs in three engines from a file and in a scripts-only sandboxed frame, and runs nothing in a fully sandboxed frame: Chromium checked in a same-origin frame only.
- The 788 templates render, mount, round-trip and log the same messages: not repeated.
- The listed tests pass: verified for the four changed render test files (346 tests) and the docsite preview test (29 tests); the rest not run.
- ESLint, the declaration typecheck and the changeset check are clean: ESLint and the changeset check verified; the CLI's strict typecheck shows no error in the changed files.
- The test helper runs inline module scripts after parsing, in strict mode, with no top-level
this, reporting a throw as the window's error event: verified by reading; under JSDOM an undeclared write still succeeds inside its strict wrapper. - Stacked on #12752: verified, its head is this pull request's base.
Files:
.changeset/render-module-script.md: clear.apps/docsite/scripts/generate-landing-template-previews.mjs: clear.apps/docsite/src/__tests__/landing-template-previews.test.ts: clear.packages/cli/api/render/render.interactive.test.mjs: non-blocking (the classic-script test covers the page's own file, not a package).packages/cli/api/render/render.notes.test.mjs: clear.packages/cli/api/render/render.test.mjs: clear.packages/cli/foundation/render/client-bundle.mjs: finding (the gate does not check bundled code for the current-script lookup).packages/cli/foundation/render/page-worker.mjs: clear.packages/cli/foundation/render/remote-images.test.mjs: clear.packages/cli/foundation/render/render-page.mjs: clear.packages/cli/test-utils/page-dom.mjs: clear (its JSDOM limit is noted above).
6834bf6 to
5d568e1
Compare
56647bf to
d3adc76
Compare
|
/approve-spec d3adc76 |
5d568e1 to
0d8a25a
Compare
d3adc76 to
c5c04ba
Compare
|
/approve-spec c5c04ba |
0d8a25a to
45551bb
Compare
c5c04ba to
1a04954
Compare
|
/approve-spec 1a04954 |
b7d1fad to
e338936
Compare
8ce9268 to
0d8ce5c
Compare
There was a problem hiding this comment.
Approved pending CI: CI has not run on this head yet.
The earlier blocking point is fixed: a page whose bundle reads document.currentScript now keeps a classic script, and a test covers it, as does the new fixture for a node_modules package without 'use strict'.
Smaller point: under JSDOM, pageDom() (packages/cli/test-utils/page-dom.mjs) does not reject an assignment to an undeclared name inside its strict wrapper, so its header's "in strict mode … as a browser does" overstates what the render tests can catch; one sentence there would help.
Claims and files checked
Review mode: full; reason: rebase
Claims:
- Changeset: an exported page's script is a module script when it runs the same in strict mode: verified (the gate in
client-bundle.mjs:941-964; in Chromium a strict package's page gets a module script and works), ES-module code being strict by definition. - Changeset: the module script runs once the file is parsed, so the browser paints before the script draws: consistent with how browsers run module scripts; timing not measured here.
- Changeset: first paint about 200 ms sooner on the measured small pages on a slow phone, with about the same time until the page responds: the author's measurement, not repeated.
- Changeset: a page that bundles CommonJS code that does not ask for strict mode, or code that reads the current-script value, keeps a classic script: verified (
render.interactive.test.mjs:194and:228; Chromium for a package without the directive, one withwith, and one that reads the current script). - Before, a classic script at the end of the body ran before the first paint on a page that arrives at once: verified, the base writes a plain
<script>last in the body. - The page's script is now a module script, runs once the document is parsed, and the file is otherwise the same: verified with the exception the description states below it.
- Experimental export output only, with no option, result field, type or render format change: verified (package manifest, command docs,
render()result and the render format line are unchanged). - The script tag of an exported page is a module script, with nothing for the caller to decide: verified with the same stated exception; no option is added.
- A frame that blocks scripts still shows the markup, and the source block, its note and the way back are unchanged: verified (Chromium: a fully sandboxed frame shows the markup and runs nothing; the source-block reader finds the block by its type).
- A module script is written only when esbuild's module parse accepts the bundle and every non-ES file asks for strict mode; other pages and pages that read the current script keep a classic script; the docsite previews strip either kind: verified (gate code; tests;
landing-template-previews.test.ts:192). - Running the mount on a later event or a timer was rejected as slower: design rationale, not measured.
- Phone and desktop timings and unchanged file sizes: the author's measurements, not repeated; the tag adds 14 bytes.
- The script runs in three engines from a file and in a scripts-only sandboxed frame under a script-src policy, and runs nothing in a fully sandboxed frame: verified in Chromium for each case; Firefox and WebKit not checked.
- The 788 page templates render, mount, round-trip and log the same messages: not repeated.
- The listed tests pass: verified for the four changed render test files (351 tests), the docsite preview test (29), and 23 more of the listed files (the rest of the render folders, export-name, doc-loads, text-json-parity, pages-landing: 655 tests); the template and browser chart files not run.
- ESLint, the declaration typecheck and the changeset check are clean: ESLint on the changed files and the changeset check verified; the declaration typecheck not run.
- The test helper runs inline module scripts once the document is parsed, in strict mode, with no top-level
this, and reports a throw as the window's error event: verified by reading and under JSDOM (it runs before the document's loaded event); JSDOM does not reject an undeclared write inside it (non-blocking note). - Stack order #12345, #12752, #12761, and stacked on #12752: verified, each head contains the one before and #12752's head is this pull request's base.
- Preflight passed at an earlier head, and only the first stack entry's changeset wording changed up to the named stack head: verified for the heads named; the reviewed head is a later rebase whose own patch differs from them only by one reformatted test statement.
Files:
.changeset/render-module-script.md: clear.apps/docsite/scripts/generate-landing-template-previews.mjs: clear.apps/docsite/src/__tests__/landing-template-previews.test.ts: clear.packages/cli/api/render/render.interactive.test.mjs: clear.packages/cli/api/render/render.notes.test.mjs: clear.packages/cli/api/render/render.test.mjs: clear.packages/cli/foundation/render/client-bundle.mjs: clear.packages/cli/foundation/render/page-worker.mjs: clear.packages/cli/foundation/render/remote-images.test.mjs: clear.packages/cli/foundation/render/render-page.mjs: clear.packages/cli/test-utils/page-dom.mjs: non-blocking (JSDOM does not reject an undeclared write inside its strict wrapper).
| * runs them. JSDOM runs classic scripts but not module scripts, and a | ||
| * rendered page's script is an inline module: this runs each inline module | ||
| * once the document is parsed (readyState interactive, before | ||
| * DOMContentLoaded), in strict mode, with no `this` at its top |
There was a problem hiding this comment.
Non-blocking: under JSDOM an assignment to an undeclared name inside this 'use strict' wrapper still succeeds (counted = 1 leaves typeof counted as 'number' and fires no error event), so a render test cannot see the main strict-mode failure the gate guards against. One sentence here saying so would keep later tests from relying on it.
e338936 to
21ed031
Compare
0d8ce5c to
5cbe43d
Compare
|
/approve-spec 5cbe43d |
There was a problem hiding this comment.
Approved pending CI: CI has not run on this head yet.
The earlier blocking point stays fixed: a page whose bundle reads document.currentScript keeps a classic script, with a test, and a node_modules package without 'use strict' has its own fixture.
Two small test points, neither blocking: pageDom()'s header (packages/cli/test-utils/page-dom.mjs) says it runs modules "in strict mode … as a browser does", but under JSDOM an assignment to an undeclared name inside its wrapper still succeeds; and render.test.mjs:848 still finds the page script with lastIndexOf('<script>'), which on a module page matches a string inside the bundled react-dom rather than the tag, so slicing from '-->\n<script' would make it independent of React's text.
Claims and files checked
Review mode: full; reason: rebase
Claims:
- Changeset: an exported page's script is a module script when it runs the same in strict mode: verified (the gate in
client-bundle.mjs:941-965; in Chromium a strict package's page gets a module script and works), ES-module code being strict by definition. - Changeset: the module script runs once the file is parsed, so the browser paints before the script draws: consistent with how browsers run module scripts; timing not measured here.
- Changeset: first paint about 200 ms sooner on the measured small pages on a slow phone, with about the same time until the page responds: the author's measurement, not repeated.
- Changeset: a page that bundles CommonJS code that does not ask for strict mode, or code that reads the current-script value, keeps a classic script: verified (
render.interactive.test.mjs:194and:228; Chromium for a package without the directive, one withwith, and one that reads the current script). - Before, a classic script at the end of the body ran before the first paint on a page that arrives at once: verified that the base writes a plain
<script>last in the body; the timing follows from how browsers run such scripts. - The page's script is now a module script, runs once the document is parsed, and the file is otherwise the same: verified with the exception the description states below it.
- Experimental export output only, with no option, result field, type or render format change: verified (package manifest, command docs,
render()result and the render format line are unchanged). - The script tag of an exported page is a module script, with nothing for the caller to decide: verified with the same stated exception; no option is added.
- A frame that blocks scripts still shows the markup, and the source block, its note and the way back are unchanged: verified (Chromium: a fully sandboxed frame shows the markup and runs nothing; the source-block reader finds the block by its type).
- A module script is written only when esbuild's module parse accepts the bundle and every non-ES file asks for strict mode; other pages and pages that read the current script keep a classic script; the docsite previews strip either kind: verified (gate code; tests;
landing-template-previews.test.ts:192). - Running the mount on a later event or a timer was rejected as slower: design rationale, not measured.
- Phone and desktop timings and unchanged file sizes: the author's measurements, not repeated; the tag adds 14 bytes.
- The script runs in three engines from a file and in a scripts-only sandboxed frame under a script-src policy, and runs nothing in a fully sandboxed frame: verified in Chromium for each case; Firefox and WebKit not checked.
- The 788 page templates render, mount, round-trip and log the same messages: not repeated.
- The listed tests pass: verified for the four changed render test files (351 tests), the docsite preview test (29), and 23 more of the listed files (the rest of the render folders, export-name, doc-loads, text-json-parity, pages-landing: 657 tests); the template and browser chart files not run.
- ESLint, the declaration typecheck and the changeset check are clean: ESLint on the changed files and the changeset check verified; the declaration typecheck not run.
- The test helper runs inline module scripts once the document is parsed, in strict mode, with no top-level
this, and reports a throw as the window's error event: verified by reading and under JSDOM; JSDOM does not reject an undeclared write inside it (non-blocking note). - Stack order #12345, #12752, #12761, and stacked on #12752: verified, each head contains the one before and #12752's head is this pull request's base.
- Preflight passed at this head: the author's run, not repeated.
Files:
.changeset/render-module-script.md: clear.apps/docsite/scripts/generate-landing-template-previews.mjs: clear.apps/docsite/src/__tests__/landing-template-previews.test.ts: clear.packages/cli/api/render/render.interactive.test.mjs: clear.packages/cli/api/render/render.notes.test.mjs: clear.packages/cli/api/render/render.test.mjs: non-blocking (line 848 finds the page script through a string inside the bundle).packages/cli/foundation/render/client-bundle.mjs: clear.packages/cli/foundation/render/page-worker.mjs: clear.packages/cli/foundation/render/remote-images.test.mjs: clear.packages/cli/foundation/render/render-page.mjs: clear.packages/cli/test-utils/page-dom.mjs: non-blocking (JSDOM does not reject an undeclared write inside its strict wrapper).
21ed031 to
0b1eda9
Compare
5cbe43d to
be361ac
Compare
|
/approve-spec be361ac |
There was a problem hiding this comment.
Approved pending CI: CI has not run on this head yet.
The rebase onto current main keeps the change as it was approved: a page whose bundle needs sloppy mode or reads document.currentScript keeps a classic script, with tests. Three small points, none blocking:
- A strict CommonJS package that calls
document.writewhile it loads still gets a module script, and the browser drops the write with no error or render warning;client-bundle.mjs:950could treatdocument.writeas it treatscurrentScript. pageDom()'s header (packages/cli/test-utils/page-dom.mjs) says it runs modules "in strict mode … as a browser does", but under JSDOM an assignment to an undeclared name inside its wrapper still succeeds.render.test.mjs:984still finds the page script withlastIndexOf('<script>'), which on a module page matches a string inside the bundled react-dom rather than the tag; slicing from'-->\n<script'would make it independent of React's text.
Claims and files checked
Review mode: full; reason: rebase
Claims:
- Changeset: an exported page's script is a module script when it runs the same in strict mode: verified (the gate in
client-bundle.mjs:947-971; in Chromium a strict package's page gets a module script and works). - Changeset: the module script runs once the file is parsed, so the browser paints before the script draws: consistent with how browsers run module scripts; timing not measured here.
- Changeset: first paint about 200 ms sooner on the measured small pages on a slow phone, with about the same time until the page responds: the author's measurement, not repeated.
- Changeset: a page that bundles CommonJS code that does not ask for strict mode, or code that reads the current-script value, keeps a classic script: verified (
render.interactive.test.mjs:194and:229; Chromium for a package without the directive, one withwith, and one that reads the current script). - Before, a classic script at the end of the body ran before the first paint on a page that arrives at once: verified that the base writes a plain
<script>last in the body; the timing follows from how browsers run such scripts. - The page's script is now a module script, runs once the document is parsed, and the file is otherwise the same: verified with the exception the description states below it.
- Experimental export output only, with no option, result field, type or render format change: verified (package manifest, command docs,
render()result and the render format line are unchanged). - The script tag of an exported page is a module script, with nothing for the caller to decide: verified with the same stated exception; no option is added.
- A frame that blocks scripts still shows the markup, and the source block, its note and the way back are unchanged: verified (Chromium: a fully sandboxed frame shows the markup and runs nothing; the template tests give every page back exactly).
- A module script is written only when esbuild's module parse accepts the bundle and every non-ES file asks for strict mode; other pages and pages that read the current script keep a classic script; the docsite previews strip either kind: verified (gate code; tests;
landing-template-previews.test.ts:192); a load-timedocument.writeis a module-script difference outside this strict-mode claim (first point above). - Running the mount on a later event or a timer was rejected as slower: design rationale, not measured.
- Phone and desktop timings and unchanged file sizes: the author's measurements, not repeated; the tag adds 14 bytes.
- The script runs in three engines from a file and in a scripts-only sandboxed frame under a script-src policy, and runs nothing in a fully sandboxed frame: verified in Chromium for each case; Firefox and WebKit not checked.
- The page templates render, mount, round-trip and log the same messages as the base: render and exact round trip verified (the template slice tests pass); mounting and console parity not repeated.
- The listed tests pass: verified for the four changed render test files (371 tests), the docsite preview test (29), 23 more of the listed files (678) and the template slices (5); the browser chart file not run.
- ESLint, the declaration typecheck and the changeset check are clean: ESLint on the changed files and the changeset check verified; the declaration typecheck not run.
- The test helper runs inline module scripts once the document is parsed, in strict mode, with no top-level
this, and reports a throw as the window's error event: verified by reading and under JSDOM; JSDOM does not reject an undeclared write inside it (second point above). - Stack order #12345, #12752, #12761, and stacked on #12752: verified, each head contains the one before and #12752's head is this pull request's base.
- Preflight passed at this head: the author's run, not repeated.
Files:
.changeset/render-module-script.md: clear.apps/docsite/scripts/generate-landing-template-previews.mjs: clear.apps/docsite/src/__tests__/landing-template-previews.test.ts: clear.packages/cli/api/render/render.interactive.test.mjs: clear.packages/cli/api/render/render.notes.test.mjs: clear.packages/cli/api/render/render.test.mjs: non-blocking (line 984 finds the page script through a string inside the bundle).packages/cli/foundation/render/client-bundle.mjs: non-blocking (a load-timedocument.writestill gets a module script).packages/cli/foundation/render/page-worker.mjs: clear.packages/cli/foundation/render/remote-images.test.mjs: clear.packages/cli/foundation/render/render-page.mjs: clear.packages/cli/test-utils/page-dom.mjs: non-blocking (JSDOM does not reject an undeclared write inside its strict wrapper).
| async function runsAsModule(esbuild, code, metafile) { | ||
| // A module script has no `document.currentScript` (it is null), so code | ||
| // that reads it while it loads keeps a classic script. | ||
| if (/\bcurrentScript\b/.test(code)) return false; |
There was a problem hiding this comment.
Non-blocking: a module script also ignores document.write once the document is parsed. A strict CommonJS package that writes while it loads gets <script type="module"> here, and in Chromium its text never appears, with no error or render warning; the base file shows it. Returning false when the bundle matches /\bdocument\.write(?:ln)?\b/, as this line does for currentScript, keeps such pages on the classic script; otherwise the JSDoc's "runs the same as a module script" could name the gap.
0b1eda9 to
fb84415
Compare
be361ac to
15c312f
Compare
|
/approve-spec 15c312f |
There was a problem hiding this comment.
Approved pending CI: CI has not run on this head yet.
The rebase onto current main leaves the change as it was: a strict page gets a module script that still mounts and responds, and a page whose bundle needs sloppy mode or reads document.currentScript keeps a classic script. Two small points, neither blocking:
- A strict CommonJS package that calls
document.writewhile it loads still gets a module script, and the browser drops the write with no error or render warning;client-bundle.mjs:950could treatdocument.writeas it treatscurrentScript. pageDom()'s header (packages/cli/test-utils/page-dom.mjs) says modules run in strict mode as a browser does, but under JSDOM an assignment to an undeclared name inside its wrapper still succeeds.
The earlier note about render.test.mjs finding the page script with lastIndexOf('<script>') is withdrawn: the base's classic file has the same match inside React DOM, so it does not come from this change.
Claims and files checked
Review mode: full; reason: rebase
Claims:
- Changeset: an exported page's script is a module script when it runs the same in strict mode: verified (the gate in
client-bundle.mjs:947-971and the tag atrender-page.mjs:2489; a strict page gets a module script in the tests and in Chromium). - Changeset: the module script runs once the file is parsed, so the browser paints before the script draws: consistent with how browsers run module scripts; timing not measured here.
- Changeset: first paint about 200 ms sooner on the measured small pages on a slow phone, with about the same time until the page responds: the author's measurement, not repeated.
- Changeset: a page that bundles CommonJS code that does not ask for strict mode, or code that reads the current-script value, keeps a classic script: verified (
render.interactive.test.mjs:194and:229; Chromium for a sloppy package). - Before, a classic script at the end of the body ran before the first paint on a page that arrives at once: verified that the base writes a plain
<script>last in the body; the timing follows from how browsers run such scripts. - The page's script is now a module script that runs once the document is parsed, and the file is otherwise the same: verified, with the exception the description states below it; the tag adds 14 bytes.
- Experimental export output only, with no option, result field, type or render format change: verified (package exports, command docs, the
render()result type and the render format note are unchanged). - The script tag of an exported page is a module script, with nothing for the caller to decide: verified with the same stated exception; no option is added.
- A frame that blocks scripts still shows the markup, and the source block, its note and the way back are unchanged: the markup precedes the script, the block and note are unchanged (
render.notes.test.mjs:156) and the round-trip tests pass; a script-blocking frame was not re-checked at this head. - A module script is written only when esbuild's module parse accepts the bundle and every non-ES file asks for strict mode; other pages and pages that read the current script keep a classic script; the docsite previews strip either kind: verified (gate code; tests;
landing-template-previews.test.ts:180); a load-timedocument.writeis a module-script difference outside this claim (first point above). - Mounting on a later event or a timer was rejected as slower: design rationale, not measured.
- Phone and desktop timings and unchanged file sizes: the author's measurements, not repeated.
- The script runs in three engines from a file and in a scripts-only sandboxed frame under a script-src policy, and runs nothing in a fully sandboxed frame: verified in Chromium from a local server (the module page mounts and its button responds); file, frame, Firefox and WebKit not checked here.
- The page templates render, mount, round-trip and log the same messages as the base: render and exact round trip verified for the template slices; mounting and console parity not repeated.
- The listed tests pass and the browser chart test skips: verified for the changed render suites (538 tests), the docsite preview test (28) and the other listed files with the template slices (527); the browser chart file not run.
- ESLint, the declaration typecheck and the changeset check are clean: ESLint on the changed files and the changeset check verified; the declaration typecheck not run.
- The test helper runs inline module scripts once the document is parsed, in strict mode, with no top-level
this, and reports a throw as the window's error event: verified by reading and under JSDOM; JSDOM does not reject an undeclared write inside it (second point above). - Stack order #12345, #12752, #12761, stacked on #12752: verified, each head contains the one before and #12752's head is this pull request's base.
- Preflight passed: the author's run names the head before the rebase; not repeated.
Files:
.changeset/render-module-script.md: clear.apps/docsite/scripts/generate-landing-template-previews.mjs: clear.apps/docsite/src/__tests__/landing-template-previews.test.ts: clear.packages/cli/api/render/render.interactive.test.mjs: clear.packages/cli/api/render/render.notes.test.mjs: clear.packages/cli/api/render/render.test.mjs: clear.packages/cli/foundation/render/client-bundle.mjs: non-blocking (a load-timedocument.writestill gets a module script).packages/cli/foundation/render/page-worker.mjs: clear.packages/cli/foundation/render/remote-images.test.mjs: clear.packages/cli/foundation/render/render-page.mjs: clear.packages/cli/test-utils/page-dom.mjs: non-blocking (JSDOM does not reject an undeclared write inside its strict wrapper).
A classic script at the end of the body runs as soon as the parser reaches it. On a page small enough to arrive at once, that is before the browser first paints, so the first paint waited for the script. A module script runs once the document is parsed, so the browser paints the markup first. A module script runs in strict mode, so the script is one only when it runs the same there: a module parse accepts it, and every file in it that is not an ES module asks for strict mode itself. A page that bundles a CommonJS package written for sloppy mode keeps a classic script. The tests run a page's module script with a JSDOM helper in test-utils (JSDOM runs only classic scripts); the docsite's landing previews strip either script. [skip ci]
fb84415 to
e304ec6
Compare
15c312f to
b497ff6
Compare
|
/approve-spec b497ff6 |
Stack: #12345 → #12752 → #12761
User need
A small exported page can arrive all at once. Its script is a classic script at the end of the body, so the browser runs it as soon as the parser reaches it, before the first paint. The viewer sees nothing until the script has run, even though the file already holds the whole page's markup.
Problem and solution fit
The page's script is now a module script (
<script type="module">). A module script runs once the document is parsed, so the browser paints the markup first and then the script draws the page over it. The file is otherwise the same.Current specification
Experimental
astryx experimental exportoutput only. No option, result field, type or render format changes.Public delta and caller burden
<script type="module">. Nothing for the caller to decide.--reverseare unchanged.document.currentScript(null in a module script), keeps a classic script, as the changeset says; the docsite's landing previews strip either kind.Design and alternatives
DOMContentLoadedfrom a classic script: rejected, because time to interactive got about 186 ms worse on a phone profile.Evidence
On 81 phone-sized dark pages, at 3 runs each on a 4× slowed phone profile, against the base:
Browsers: in Chromium, WebKit and Firefox the script runs and a click changes the page, both from
file://and inside asandbox="allow-scripts"frame with a script-src CSP. Withsandbox=""the frame shows the markup and runs nothing.The 788 page templates render, mount, reverse exactly and log the same console messages as the base.
Scope
Components: packages/cli (foundation/render/render-page.mjs, foundation/render/client-bundle.mjs, foundation/render/page-worker.mjs, test-utils/page-dom.mjs), apps/docsite (scripts/generate-landing-template-previews.mjs and its test)
Testing
CI=1 pnpm vitest runon packages/cli/test/export-name.test.mjs, every file in packages/cli/foundation/render and packages/cli/api/render, foundation/doc-compiler/doc-loads.test.mjs, text-json-parity, .github/scripts/pages-landing.test.mjs and the docsite's landing-preview tests. All pass; the browser chart test skips as on main. eslint, the api-dts typecheck andcheck:changesetsare clean. JSDOM runs only classic scripts, so the render tests open pages withtest-utils/page-dom.mjs. It runs each inline module script once the document is parsed, in strict mode, with no top-levelthis, and reports a throw as the window'serrorevent, as a browser does.Stacked on #12752.
preflight: pass be361ac