Fixes#6440
## Description
Static exports currently omit Text pages such as `/robots.txt`,
`/ads.txt`, and `/.well-known/security.txt`. This generates their
routes, evaluates content through the existing page-data loader, and
uses Vike's native `pageContext.content` to write the exact text at the
configured file path.
Internal route directories are separate from public URLs so dot-prefixed
paths work. No generated writer script, text-page manifest, HTML
wrapper, or post-build file rewrite is needed.
## Dependencies
- Pin Vike to `0.4.267-commit-feffb0f`: native non-HTML output is
published in this commit prerelease but is not yet in stable `0.4.267`.
- Use Vite `7.1.12` and the compatible React plugin for SSG. Build
through `vike build && vike prerender` so Vike uses its matching Vite
dependency.
- Update React Router's `vite-node` dependency to `3.2.4` for
compatibility with the CLI's Vite 7 test environment.
## Validation
- All 1,173 CLI tests pass locally across 72 files, including all 79
prebuild tests for normal HTML, dynamic SSG routes, and React Router
builds.
- Text export coverage checks exact output for `/robots.txt`,
resource-backed `/.well-known/security.txt`, empty text, Unicode, and
HTML-like content.
- CLI and SSG fixture type checks, lint, and formatting pass locally.
- SSG fixtures regenerated; the packaged SSG test passes locally.
- All executed GitHub CI checks pass at
`201fa971616bb607ca35ee24a970f107eddee754`, including all six browser
shards. Shard 4 passed on retry after an MDX template rename timeout.
Visual regression is skipped and preview deployment remains gated.
- Corrected the existing animation navigation test for fork CI: wait for
the rendered component with the public fallback and retain the animation
initialization assertion when the private module is present.
## Manual verification
1. Export a static project with Text pages at `/robots.txt` and
`/.well-known/security.txt`.
2. Run the generated project's build.
3. Confirm both files under `dist/client` contain exactly the configured
text, including resource expressions.
4. Confirm normal pages still render HTML.
- [ ] Original author tested the updated export and confirmed it works.
- [ ] Preview tested (deployment approval remains gated).
---------
Co-authored-by: Sviat Barbutsa <9897782+sviat-barbutsa@users.noreply.github.com>
Co-authored-by: Oleg Isonen <oleg008@gmail.com>
Closes#6057
## Outcome
Generated projects now reject Node.js versions older than 22.12 before
React Router, Remix, or Vite evaluates SDK components. Users see the
package-manager engine error with the current and required versions
instead of the indirect `sanitize-html` / `htmlparser2`
`ERR_REQUIRE_ESM` stack trace.
## Root cause
`sanitize-html@2.17.6` synchronously loads the ESM-only
`htmlparser2@12`. That dependency combination relies on synchronous
`require(ESM)` support, which Node.js enabled by default in 22.12.
Generated projects incorrectly declared the broader `>=22` range,
allowing an unsupported runtime to reach SSR evaluation.
## Implementation
- Set the CLI and all generated base templates to `engines.node:
>=22.12.0`.
- Add npm `devEngines.runtime` with `onFail: error`, which runs before
install, CI, and run commands.
- Enable `engine-strict` in generated npm configuration so pnpm also
rejects an unsupported runtime.
- Regenerate every tracked CLI fixture package manifest.
- Update CLI documentation and the release-smoke manifest contract.
- Remove the earlier sanitizer-bundling workaround from the branch;
sanitizer code and packaging are unchanged from `main`.
## Checklist
- [x] Declare the exact Node.js compatibility floor
- [x] Fail before generated development, build, and start commands
- [x] Cover the generated engine contract with a fail/pass regression
- [x] Regenerate and inspect all affected fixtures
- [x] Review documentation impact and update the CLI guide
- [x] Keep sanitizer behavior and SDK packaging unchanged
## Verification
- Regression demonstrated failing before the template metadata change
and passing afterward
- `pnpm --filter webstudio test` — 946 passed
- `pnpm --filter webstudio typecheck`
- `pnpm --filter webstudio build`
- `pnpm fixtures`
- `pnpm lint`
- `pnpm exec oxfmt --check` on changed source, template, fixture, and
documentation files
- `git diff --check`
Agent evaluations were not run because they require separate approval.
Closes#4119
Supersedes #5999 after GitHub closed it during the head-branch rename.
## Approach
Code Text uses one optional public highlighting boundary:
- `@webstudio-is/sdk-components-react/code-text` → `src/code-text.tsx`
The ordinary `components` entry remains Shiki-free. Canvas loading,
metadata options, theme variables, and the plain semantic `<code>`
component remain private implementation details.
**Code** uses the code editor. **Language** and **Theme** use normal
bindable selects. Fixed selections generate direct imports for only the
per-page language/theme union; plaintext imports no grammar. Bound
selections generate Shiki's lazy language/theme registries.
SSR and client rendering share the same factory. Missing bound assets
suspend the first render while SSR resolves the selected modules. SSG
now waits for Suspense before serializing HTML. During hydration the
completed server markup stays in place while the browser fetches only
the selected language and theme. Later client-side binding changes load
only the new selections and keep the same `<code>` node and focus.
Highlighted output preserves the semantic root, ref, author
classes/styles, whitespace, escaped source, and legacy children/native
`lang` behavior. Shiki's implicit tab stop is disabled. A color-only
transformer strips theme typography so asynchronous highlighting cannot
change text geometry.
## Bundle impact
Measured from same-commit production React Router + Cloudflare builds
containing one JavaScript / GitHub Light Code Text instance. Sizes are
the sum of emitted JavaScript files; gzip is the sum of each file
compressed independently.
| Worker output | Files | Raw | Sum gzip |
| --- | ---: | ---: | ---: |
| Fixed selections | 3 | 1,341,851 B | 288,342 B |
| Bound selections | 310 | 10,372,112 B | 1,872,273 B |
| Increase | +307 | +9,030,261 B (8.61 MiB) | +1,583,931 B (1.51 MiB) |
The bound browser build also emits the catalog as lazy chunks:
+9,012,594 raw bytes / +1,578,779 sum-gzip bytes across the complete
deployed output. Those chunks are not all delivered on page load. The
production SSG regression verifies 100+ catalog chunks are emitted while
the HTML directly module-preloads only one shared runtime chunk; the
browser fetches the runtime-selected language/theme modules on demand.
## Tradeoffs and compatibility
- Instances with both highlighting properties unset keep the legacy
plain renderer.
- Static highlighting still requires both **Language** and **Theme**.
- Binding either selection includes that catalog in deploy output
because its runtime value is not known at publish time.
- The syntax-highlighting property is `language`; legacy native HTML
`lang` remains preserved.
- Invalid or unavailable runtime selections render as plain code.
- Fixed selections retain the smallest publish output; bound selections
trade deploy/worker size for runtime flexibility.
## Todo
- [x] Restore the specialized Code Text component and semantic plain
fallback
- [x] Use a code editor for Code and bindable selects for Language and
Theme
- [x] Persist JavaScript / GitHub Light template defaults
- [x] Collapse highlighting to one public `./code-text` entry
- [x] Keep canvas loaders and option/theme helpers private
- [x] Generate direct imports for fixed selections and omit plaintext
grammar
- [x] Generate lazy catalogs when Language or Theme is bound
- [x] Preserve highlighted SSR markup during hydration without
node/focus movement
- [x] Support Suspense-aware highlighted SSG output
- [x] Preserve escaping, accessibility, legacy children, and native
`lang`
- [x] Measure fixed versus bound Cloudflare worker output
- [x] Deep-review correctness, DRYness, package surface, and obsolete
binding infrastructure
- [x] Review documentation impact and update Code Text documentation
- [x] Run focused tests, typechecks, production builds, formatting, and
staged diff review
- [ ] Fixture pipeline — blocked during sync because the current API
rejects this local CLI version as incompatible; no fixture output
changed
## Verification
- [x] New/changed regressions were demonstrated failing without their
behavior and passing after restoration
- [x] SDK Code Text metadata, rendering, hydration, and bundle tests: 17
passed
- [x] Component registry tests: 3 passed
- [x] CLI asset collection and full prebuild suite: 59 passed
- [x] SDK components, component registry, SDK, and CLI typechecks
- [x] SDK components declaration and production builds
- [x] Component registry production build
- [x] Production Vite + Vike prerender emits highlighted bound SSG HTML
with one doctype
- [x] Dynamic catalog chunks remain outside the SSG page's direct
preload set
- [x] Documentation reviewed and updated
- [x] Formatting and staged diff checks
## Summary
- add a reusable pre-publish audit pipeline with normalized findings and
extensible checks
- validate HTML content-model nesting and existing resource integrity
before regular and static publishing
- identify the affected page and instance in invalid-markup errors
- move generated HTML formatting from automatic `postbuild` to the
explicit local `build:debug` command
## Root cause
A project contained an invalid stored component hierarchy, with an `h2`
nested inside a paragraph. The Builder did not run a holistic
content-model validation before publishing, so the invalid hierarchy
reached static generation. The static fixture then ran `oxfmt`
automatically during `postbuild`; its parse failure made the otherwise
completed static build fail.
## Impact
Users now see a specific Builder error before publishing, including the
affected page and invalid nesting. Static publish CI no longer formats
generated HTML automatically, while developers can still produce
formatted output locally with `pnpm build:debug`.
## Validation
- 65 focused project-build tests passed
- `@webstudio-is/project-build` typecheck passed
- `@webstudio-is/builder` typecheck passed
- focused Oxlint passed
- focused Oxfmt check passed
- `git diff --check` passed
This update helps AI agents understand, audit, and visually verify
Webstudio projects more reliably. It also adds clearer guidance for
expressions, Collections, screenshots, and responsive rendered audits.
### Audit complete projects
- Run one `audit` command across accessibility, SEO, security, assets,
styles, and performance.
- Audit the whole project or focus on a specific page, scope, or
severity.
- Receive stable findings with locations, explanations, and recommended
fixes.
- Continue large result sets through pagination without repeating
general guidance.
### Audit the rendered website
- Build and inspect the generated website, rather than relying only on
stored project data.
- Check every static page at representative mobile, tablet, and desktop
widths.
- Use one suitable viewport inside each configured breakpoint range.
- Reuse the same browser and resize pages between captures for
substantially faster audits.
- Process multiple pages concurrently while keeping resource use
bounded.
- Supply concrete examples for dynamic routes such as blog posts.
- Review and confirm unusually large screenshot plans before they run.
### Find visual and performance problems
Rendered audits can detect:
- Horizontal page overflow.
- Broken images.
- Images loaded eagerly below the fold.
- Images that are much larger than their rendered size.
- Render-blocking resources.
- Legacy font formats.
- Pages that fail to load or redirect somewhere unexpected.
- Pages captured before their layout becomes stable.
Detailed screenshots, measurements, failures, and timing evidence are
saved locally for further inspection.
### Capture generated pages directly
- Capture a project route with `webstudio screenshot --path /route`.
- Automatically generate and start a temporary production-style preview.
- Stop the temporary preview after the screenshot is captured.
- Return navigation, responsive layout, and page-size evidence with JSON
output.
- Allow external image domains needed by the generated preview.
### Reuse generated previews
- Cache generated preview builds when the project has not changed.
- Reuse preview dependencies across regenerations.
- Keep preview dependencies isolated from the user’s project
dependencies.
- Surface preview build and startup failures with useful diagnostic
output.
- Include local project assets in generated previews.
### Author Collections correctly
- Explain when Collection is required for arrays and objects.
- Guide agents to bind the complete iterable instead of one item or the
response wrapper.
- Explain how Collection repeats its children for every entry.
- Explain current-item and current-key scope.
- Preserve Webstudio’s generated Collection parameters.
- Guide agents to use stable values for repeated interactive components.
### Write expressions with fewer mistakes
- Add a dedicated `webstudio://project/expressions` reference.
- Document expression scope, supported syntax, and supported methods.
- Explain how resources, variables, Collections, actions, and `system`
values are accessed.
- Distinguish fixed values from runtime expressions.
- Provide valid examples for text, props, resource URLs, headers, query
parameters, and bodies.
- Warn agents that valid syntax does not guarantee that runtime data has
the expected shape.
### Improve agent discovery
- Make Collection and expression workflows discoverable through
`meta.guide`.
- Return Collection-specific instructions through `components.get`.
- Point relevant command schemas to the expression reference.
- Keep detailed guidance available without placing it in every tool
response.
### Improve audit reliability
- Report which rendered captures passed, found issues, failed, or were
skipped.
- Distinguish planning, preview, capture, and cleanup failures.
- Include actionable retry instructions with rendered failures.
- Preserve completed evidence when part of an audit fails.
- Detect stale or conflicting preview servers more clearly.
- Support cancellation and bounded capture timeouts.
### Improve packaged CLI verification
- Add a release-shaped CLI smoke test.
- Install the packed CLI in an isolated temporary project.
- Fail on peer-dependency warning floods.
- Verify preview, screenshots, MCP calls, rendered audits, and generated
assets.
- Confirm that generic React Router previews do not include Docker-only
image dependencies.
- Keep CLI and MCP stdout machine-readable while progress remains on
stderr.
## User Impact
Agents can now audit a real rendered Webstudio site, inspect responsive
behavior, find concrete visual and performance problems, and provide
evidence for their conclusions. They also receive much clearer
instructions when turning API data into repeated content or writing
dynamic expressions.
## prettier -> oxfmt (0.58.0)
- .oxfmtrc.json generated with `oxfmt --migrate=prettier`: trailingComma
es5, printWidth 80 (oxfmt defaults to 100), sortPackageJson disabled,
.prettierignore patterns folded in (file deleted).
- ignorePatterns additionally exclude yml/yaml/toml/jsonc and
packages/cli/templates/** so oxfmt covers exactly the file set prettier
used to format (ts,tsx,js,json,css,md) and never touches user-facing
scaffolding artifacts.
- root `format` script, nano-staged pre-commit hook and the CI check
(`pnpm oxfmt --check`, replacing `prettier --cache --check` and its
actions/cache step — oxfmt checks the whole repo in ~0.7s) now run
oxfmt.
- every generator script that ran `prettier --write` on __generated__
output now runs `oxfmt` (css-data, icons, html-data, postgrest, sdk,
sdk-components-*, apps/builder tailwind preflight).
- the four scripts that used prettier's JS `format()` API write raw
source instead and their package.json scripts pipe the generated file
through the oxfmt CLI: project-build generate-docs +
generate-runtime-operation-contracts, cli generate-docs, apps/builder
generate-server-only-api-metadata. oxfmt rejects paths containing "..",
so cross-package generated files are formatted via a subshell cd into
the owning package.
- one-time reformat: oxfmt's canonical output differs from prettier on 8
repo source files (binary-operator continuation indent, import() call
wrapping, sub-pixel spacing of empty for-clauses); oxfmt honors existing
`// prettier-ignore` comments so intentional layouts are kept.
- prettier remains ONLY as a cli devDependency for the
prettier/standalone HTML normalizer inside html-to-jsx.test.ts, and
inside fixtures/ + packages/cli/templates/ (ships to scaffolded user
projects; out of scope here).
- editor config switched from esbenp.prettier-vscode to oxc.oxc-vscode
(devcontainer extension list, .vscode editor.defaultFormatter).
## oxlint 1.56 -> 1.73
- oxlint 1.73 rules-of-hooks special-cases hooks NAMED useEffectEvent:
their results may only be called from effects. Our
app/shared/hook-utils/effect-event.ts is a stable-callback helper
(useEvent pattern), intentionally called from event handlers and passed
as props. The rule is disabled via .oxlintrc.json overrides for the five
files doing this (product code untouched); note those files lose
hook-order linting entirely until the rule becomes configurable.
## TypeScript 5.8.2 -> 7.0.2 (native compiler)
- `tsc` is now the Go-based native binary; all `tsgo` script usages
(workspace packages and fixtures) renamed back to `tsc` and
@typescript/native-preview removed (the package is being phased out).
- fixes for TS7 changed defaults and stricter checks:
- `types` now defaults to [] -> base tsconfig sets "types": ["node"]
(restores the implicit-@types/node behavior of TS5).
- `rootDir` now defaults to ./ -> every tsconfig.dts.json sets
"rootDir": "./src" (TS5011 otherwise).
- import assertions removed -> cli/src/cli.ts uses `with { type: "json"
}` (TS2880).
- stricter isolatedDeclarations inference -> explicit annotations in
css-data bin/property-filter.ts (TS9010) and image image-dev.stories.tsx
(TS9013).
- declaration serialization limit -> project-build builder-runtime.ts
runtimeOperationContracts gets an explicit type (TS7056); the annotation
preserves the narrow RuntimeOperationId union.
- TS7 ships no stable programmatic API:
- react-sdk (component-generator tests drive the compiler API) aliases
its typescript devDependency to @typescript/typescript6@^6.0.2; its bin
is `tsc6`, so the package's typecheck still runs native TS7 tsc from the
workspace root.
- generate-arg-types keeps typescript 5.8.2 for react-docgen-typescript.
- fixtures/ and packages/cli/templates/ keep typescript 5.8.2
(user-facing); fixture scripts still work because plain `tsc` resolves
to their local dependency.
## vite -> rolldown-vite 7.3.1 (oxc bundler)
- global pnpm override `"vite": "npm:rolldown-vite@^7.3.1"`: the builder
app (remix v2 vite plugin works unmodified), every package vite build
and the storybook build now bundle on rolldown/oxc.
- vitest is scoped BACK to vanilla vite via `vitest>vite`,
`vite-node>vite` and `@vitest/mocker>vite` overrides because vitest
3.1's runner does not understand rolldown's SSR transform
(__vite_ssr_exportName__ ReferenceError in every suite).
- those overrides pin vite EXACTLY to 6.3.4: letting ^6.3.4 float to
6.4.3 breaks cli prebuild tests (dynamic import of a generated
app/routes/$.tsx fails to resolve under 6.4.3's loader).
## unrelated cleanup requested during review
- apps/builder commands.ts imports duplicate-tokens-group statically
instead of via dynamic import. The circular dependency the dynamic
import guarded against only exists through the command-panel barrel
(command-panel.tsx > groups/index.ts > commands-group.tsx >
commands.ts); importing the group module directly is cycle-free
(verified with madge), matching the neighboring wrap-group and
convert-group imports.
## verification
- pnpm lint, oxfmt --check: clean.
- pnpm -r typecheck (TS7 native) and pnpm dts: clean.
- pnpm -r test: all suites pass (builder 2093 tests, cli 630, react-sdk
45, project-build 11, ...).
- builder app build, full workspace build, cli build and storybook build
all succeed on rolldown-vite.
## Description
1. What is this PR about (link the issue and add a short description)
## Steps for reproduction
1. click button
2. expect xyz
## Code Review
- [ ] hi @kof, I need you to do
- conceptual review (architecture, feature-correctness)
- detailed review (read every line)
- test it on preview
## Before requesting a review
- [ ] made a self-review
- [ ] added inline comments where things may be not obvious (the "why",
not "what")
## Before merging
- [ ] tested locally and on preview environment (preview dev login:
0000)
- [ ] updated [test
cases](https://github.com/webstudio-is/webstudio/blob/main/apps/builder/docs/test-cases.md)
document
- [ ] added tests
- [ ] if any new env variables are added, added them to `.env` file
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This PR expands Webstudio MCP and CLI into a more complete agent
authoring interface. Agents can discover project capabilities, edit real
Webstudio content, use data/resources, verify visual output, and report
useful issues when workflows fail.
## MCP User Capabilities
- Create, update, duplicate, reorder, and delete pages.
- Create pages from templates and manage reusable page templates.
- Inspect project pages, instances, props, styles, assets, variables,
resources, and metadata.
- Insert Webstudio components and authored JSX fragments into pages.
- Edit text, props, styles, breakpoints, design tokens, and CSS
variables.
- Update page metadata, SEO fields, redirects, marketplace metadata, and
project settings.
- Create and use static data variables.
- Create and use dynamic resources fetched over HTTP.
- Use REST, GraphQL, and built-in system resources in authored pages.
- Bind data variables and resources to visible page content.
- Create resource-backed pages such as sitemap XML, structured SEO data,
and API-driven content sections.
- Preview current project state without requiring a publish step.
- Capture screenshots for visual verification.
- Verify responsive designs across desktop, tablet, and mobile
breakpoints.
- Use screenshot diff and OCR-style checks to inspect rendered output.
- Reset and refresh local MCP project state when needed.
- Discover available CLI/MCP commands from generated manuals.
- Use clearer examples for resources, data variables, JSX authoring,
previewing, and visual checks.
- Read marketplace product metadata without requiring a full project
snapshot.
- Get safer guidance when using low-level patch tools.
- Get a ready-to-copy Discord report template when MCP/CLI behavior is
confusing or broken.
Closes https://github.com/webstudio-is/webstudio/issues/3991
Adds HTTP Basic Authentication support for published pages and
project-level `.wsauth` rules.
This introduces a new `@webstudio-is/wsauth` package that owns the
generic authentication format logic: parsing, validation, serialization,
route matching, resource generation, and request authentication. The
current supported method is `basic`, with the package structured so
additional auth methods can be added later.
Builder changes include:
- Page Settings now has an `Authentication` section for per-page Basic
Auth credentials.
- Project Settings now has an `Authentication` section for editing
`.wsauth` route rules.
- Page Settings was split into section-specific files with focused
tests.
- Auth UI shows Pro badges/info tooltips but remains editable.
- Publishing to custom domains is blocked on plans without `allowAuth`
when either page auth or project auth is configured.
- ProBadge now renders as a real pricing link and uses improved text
alignment.
Build/publish changes include:
- CLI prebuild generates and merges `.wsauth` entries.
- Published app templates enforce auth for HTML/XML routes.
- Generated auth resources are shared between build output and runtime.
We want to migrate more templates to react-router
so here I split docker template into react-router and
react-router-docker. Image processing, dockerfile and node environment
are left as docker specifics.
We figured assets can be loaded from shared url without additional
manipulation. Here got rid of asset origin detection and dropped
excessive --preview flag. Now local, staging and prod will work
automatically.
## Description
**✅🔍 Review per commit!!! ✅🔍**
We missed this bug because our CLI has two different sync methods:
1. Sync by buildId - This one works fine.
2. Sync by projectId - broken
This PR contains:
1. Fix
2. Fixture with sync by projectId
## Steps for reproduction
1. click button
4. expect xyz
## Code Review
- [ ] hi @kof, I need you to do
- conceptual review (architecture, feature-correctness)
- detailed review (read every line)
- test it on preview
## Before requesting a review
- [ ] made a self-review
- [ ] added inline comments where things may be not obvious (the "why",
not "what")
## Before merging
- [ ] tested locally and on preview environment (preview dev login:
5de6)
- [ ] updated [test
cases](https://github.com/webstudio-is/webstudio/blob/main/apps/builder/docs/test-cases.md)
document
- [ ] added tests
- [ ] if any new env variables are added, added them to `.env` file
