Skip to content

[experimental] export: the page's script is a module script - #12761

Open
josephfarina wants to merge 1 commit into
josephfarina/rl-class-aliasfrom
josephfarina/rl-module-script
Open

josephfarina wants to merge 1 commit into
josephfarina/rl-class-aliasfrom
josephfarina/rl-module-script

Conversation

@josephfarina

@josephfarina josephfarina commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

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 export output only. No option, result field, type or render format changes.

Public delta and caller burden

  • The script tag of an exported page is <script type="module">. Nothing for the caller to decide.
  • A frame that blocks scripts still shows the markup. The source block, its note and --reverse are unchanged.
  • A module script runs in strict mode, so the file writes one only when the script runs the same there: esbuild's module parse accepts the bundle, and every bundled file that is not an ES module (a package's CommonJS file or the page's own) asks for strict mode itself. A page that bundles CommonJS code that does not ask for strict mode, or code that reads 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

  • Running the mount on DOMContentLoaded from a classic script: rejected, because time to interactive got about 186 ms worse on a phone profile.
  • Deferring the mount with a timer or the next animation frame: rejected for the same reason (+172 ms).

Evidence

On 81 phone-sized dark pages, at 3 runs each on a 4× slowed phone profile, against the base:

  • First paint: median 200 → 184 ms, p90 320 → 236 ms. On the 9 pages whose first paint waited for the script, first paint is about 200 ms sooner.
  • Time to interactive: median −10 ms. One page is worse by more than 100 ms, three are better.
  • Desktop: first paint 136 → 92 ms, time to interactive 140 → 120 ms.
  • File sizes are the same.

Browsers: in Chromium, WebKit and Firefox the script runs and a click changes the page, both from file:// and inside a sandbox="allow-scripts" frame with a script-src CSP. With sandbox="" 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)

  • One capability is added.
  • Unrelated fixes, cleanup, and policy changes were removed or split.
  • Consumer docs, focused tests, and migration evidence ship with the feature.
  • Public text and artifacts contain no internal Meta context.

Testing

CI=1 pnpm vitest run on 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 and check:changesets are clean. JSDOM runs only classic scripts, so the render tests open pages with test-utils/page-dom.mjs. It runs each inline module script once the document is parsed, in strict mode, with no top-level this, and reports a throw as the window's error event, as a browser does.

Stacked on #12752.

preflight: pass be361ac

@vercel

vercel Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
astryx Ready Ready Preview Nov 19, 2026 8:35pm UTC

Request Review

@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Meta Open Source bot. label Nov 19, 2026
@astracat-bot

astracat-bot Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

AI review status for this pull request.

Review status Updated
🔄 In progress (for maintainers only) Nov 19, 2026, 8:20 PM UTC

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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:2166 now writes the esbuild IIFE as a module script, while client-bundle.mjs:722 still checks it with a classic vm.Script parse, so a page whose bundled CommonJS dependency uses a with statement 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 esbuild format: 'esm' or a sourceType: '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 with or 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-157 and 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 beyond pretendToBeVisual).
  • 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).

Automated review (maintainer link)

Comment thread .github/scripts/pages-landing.test.mjs Resolved

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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's no-useless-assignment ESLint rule, because every path through the catch throws, so pnpm lint and 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 at render.interactive.test.mjs:194 asserts), 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 with statement, 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).

Automated review (maintainer link)

@astracat-bot astracat-bot Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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.currentScript and no top-level this, so it runs the same in strict module mode", but runsAsModule (packages/cli/foundation/render/client-bundle.mjs:936) does not check bundled code for currentScript, so a page that bundles a package reading document.currentScript while it loads gets a module script, where that value is null, and in Chromium the page throws and never comes alive; keep the classic script when the bundle contains currentScript, 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 .js and .ts files 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-level this is 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).

Automated review (maintainer link)

@josephfarina

Copy link
Copy Markdown
Contributor Author

/approve-spec d3adc76

@josephfarina
josephfarina force-pushed the josephfarina/rl-class-alias branch from 5d568e1 to 0d8a25a Compare November 19, 2026 11:50
@josephfarina
josephfarina force-pushed the josephfarina/rl-module-script branch from d3adc76 to c5c04ba Compare November 19, 2026 11:50
@josephfarina

Copy link
Copy Markdown
Contributor Author

/approve-spec c5c04ba

@josephfarina

Copy link
Copy Markdown
Contributor Author

/approve-spec 1a04954

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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:194 and :228; Chromium for a package without the directive, one with with, 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).

Automated review (maintainer link)

* 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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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.

@josephfarina
josephfarina force-pushed the josephfarina/rl-class-alias branch from e338936 to 21ed031 Compare November 19, 2026 14:45
@josephfarina
josephfarina force-pushed the josephfarina/rl-module-script branch from 0d8ce5c to 5cbe43d Compare November 19, 2026 14:46
@josephfarina

Copy link
Copy Markdown
Contributor Author

/approve-spec 5cbe43d

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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:194 and :228; Chromium for a package without the directive, one with with, 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).

Automated review (maintainer link)

@josephfarina

Copy link
Copy Markdown
Contributor Author

/approve-spec be361ac

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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.write while it loads still gets a module script, and the browser drops the write with no error or render warning; client-bundle.mjs:950 could treat document.write as it treats currentScript.
  • 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:984 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; 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:194 and :229; Chromium for a package without the directive, one with with, 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-time document.write is 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-time document.write still 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).

Automated review (maintainer link)

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;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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.

@josephfarina

Copy link
Copy Markdown
Contributor Author

/approve-spec 15c312f

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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.write while it loads still gets a module script, and the browser drops the write with no error or render warning; client-bundle.mjs:950 could treat document.write as it treats currentScript.
  • 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-971 and the tag at render-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:194 and :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-time document.write is 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-time document.write still 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).

Automated review (maintainer link)

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]
@josephfarina
josephfarina force-pushed the josephfarina/rl-class-alias branch from fb84415 to e304ec6 Compare November 19, 2026 20:16
@josephfarina
josephfarina force-pushed the josephfarina/rl-module-script branch from 15c312f to b497ff6 Compare November 19, 2026 20:16
@josephfarina

Copy link
Copy Markdown
Contributor Author

/approve-spec b497ff6

This branch was successfully deployed

1 active deployment
Preview — b497ff6c Deployed Nov 19, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CLA Signed This label is managed by the Meta Open Source bot.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant