Aller au contenu

How the platform works inside

Ce contenu n’est pas encore disponible dans votre langue.

For builders who want to know what happens behind the ws commands. It covers what runs where, how private links and pointing at a page work, how watching a preview works, how versions and approval work, and how one fix reaches every site.

Parts 2 to 7 show what a builder sees. This page shows what they do not. Most of it is built and tested. Where this page describes a design that is not built yet, it says so.

Terms used on this page:

  • A sample is a site made for a business that has not bought it yet, at a private address on sitepeek.page. A bought site is one the business pays to host. Its owner is the person at the business who signs in to manage it.
  • A version is a saved copy of a site’s files and settings. Publishing makes one, and the newest is the one visitors see. A change waiting for approval is one a builder asked the owner to approve first, with ws push --needs-approval; it becomes a version only when the owner approves it.
  • Live data is data the platform fetches from another service, such as the weather, each time a visitor opens a page. The part of a page between {% live %} and {% endlive %} tags shows it. Below a {% fallback %} tag in the same part is what shows when the service cannot be reached.
  • The owner’s tools are the screens where the owner opens a page of the site, points at part of it, and types the change they want. That message is a request.
  • The engine is the platform code that turns a site’s files into pages. Each engine release is numbered.
  • On our servers, only Liquid runs. The platform renders a site’s Liquid when it builds a preview or a version. It renders again for each part of a page that shows live data, when a visitor opens the page. Liquid cannot run code it is not given. The platform gives it a file system holding only that version’s files. render reads only from _includes, and layouts come only from _layouts. Templates get only plain values (site, page, data, item, live, content), with no way to reach the network or the platform. Each render also has limits on time, loop steps and output size.
  • Printed values are escaped. The platform sets LiquidJS’s outputEscape option to a function. It escapes every value except HTML the platform itself marks as safe: content, the result of render, the result of the markdown filter, which removes scripts and unsafe links, and the parts that show live data. A test on 2026-11-13 with LiquidJS 10.30.1 showed why the built-in "escape" setting is not enough. It escapes content and markdown output too, and it escapes front matter twice, so “Fish & Chips” printed as Fish & Chips. The function in that test printed content, the result of markdown, and the front matter title once escaped, as intended.
  • Nothing else from a site runs on our servers. A site has no server code, no package installs and no build step of its own.
  • A site’s JavaScript runs only in visitors’ browsers, under that site’s own hostname, and, while an owner points at a page, under the owner’s frame hostname.
  • Scripts and style sheets load from the site itself, from /_ws/, and from any https address. Shopify themes, Webflow and Squarespace allow the same. ws push lists each outside domain a site loads them from. Owners never add scripts: analytics and similar tools come only from the platform’s own list, which it adds to the page and to its Content Security Policy.
  • On a site, /_ws/ serves only forms, live data, the shared libraries, the small script that updates an open preview, and the small script the owner’s tools use in their frame. The owner’s account, and everything that needs the owner’s sign-in, is only on app.websitestrategy.com. A site’s own code never sees the owner’s session.

ws preview, and ws push on a sample, print a link with a key. This is how the key works:

  1. The key is 128 random bits, written as 22 letters and numbers. The platform stores only a hash of it, with the hostname it opens, the date it ends, and a count of how many times the link was replaced, starting at 1.
  2. Opening the link swaps the key for a cookie, then redirects to the same address without the key, before any page or file loads. Every response sends Referrer-Policy: no-referrer, and request logs drop the key. So the key does not leak to other sites or into logs.
  3. The cookie is named __Host-ws_preview, with Secure, HttpOnly, SameSite=Lax and Path=/. Its value is signed, and holds the hostname, that count and the end date. It ends when the link ends.
  4. Every response on that hostname checks the cookie against the stored link: pages, files such as photos, form posts and the parts that show live data. A cookie for another hostname, an older count or a past end date gets “This preview is private”.
  5. --new-link adds 1 to that count, so every cookie the old link gave out stops working at once. Running ws preview again moves the end date, and that is checked on each response, so everyone with the link gets the extra days.
  6. Nothing private is cached where others can read it. Responses send Cache-Control: private, no-store.
  7. Form posts and requests for live data also check that the request’s Origin header is the same hostname.

The router’s tests (apps/router/test/private.test.ts) cover these cases: two browsers with one link, --new-link signing out the first browser, an expired link, and a direct request for a photo with no cookie.

What the Public Suffix List entry for sitepeek.page adds

Section titled “What the Public Suffix List entry for sitepeek.page adds”

The Public Suffix List is the list browsers use to decide which hostnames belong to separate owners. Every preview has its own hostname under sitepeek.page. On 2026-11-13, sitepeek.page is not on the list. Until it is, browsers treat all of these hostnames as parts of one site.

Once it is on the list, and browsers ship the updated list, two things change:

  • No preview can set a cookie for all of sitepeek.page, so one preview cannot plant cookies on another.
  • Browsers treat two previews as different sites, so SameSite cookies protect each from requests made by another. Some browsers also keep different sites in separate processes, but that depends on the browser and the device.

The link a preview prints already signs a browser in to one hostname only. Until the list entry ships, the host-only cookies above keep previews apart for sign-in. Adding a domain to the list needs a _psl DNS TXT record that stays in place, and the domain registered more than two years ahead. Browsers pick up the list on their own schedule, and nobody can speed that up.

Previews, samples and frames are on sitepeek.page, a domain of their own, apart from the ops panel, ops.websitestrategy.com, where Website Strategy staff manage every site.

The owner’s tools run on app.websitestrategy.com, and show the site in a frame. It was chosen over two other designs: the platform adding the owner’s tools into the page itself with the site’s scripts turned off, or the owner drawing on a screenshot. A frame keeps the site’s own scripts running while the owner points. It works in five steps:

  1. When Dana, an owner, opens a page in the owner’s tools, the app asks the platform for a hostname that shows that one version of the site, every page of it, for one hour. The platform records each page it serves on that hostname. It answers only requests to read pages and files, such as f-4kq9t2mzx7wp3hd8rc.sitepeek.page. The frame opens with a one-minute entry pass, and each later request carries a short proof signed by the owner panel. The router checks the owner’s access on every protected request, so signing out or losing access closes the frame on the next request. Forms in the frame send nothing, and nothing on that hostname can change the site. Until the Public Suffix List entry ships, this hostname shares a browser site with every other preview.
  2. Pages served on that hostname, and only there, carry a data-ws-at number on each element the platform built, and one script, /_ws/pick.js. Visitors never get either.
  3. When Dana taps part of the page, pick.js sends the app a message with the browser’s postMessage, which only pages on app.websitestrategy.com can receive. It holds the version, the page’s address, the element’s number, its text and its place on the screen. It also holds a snapshot of the page as Dana sees it at that moment: its HTML as it now stands, with any menu or tab Dana opened, the screen’s width, height and pixel ratio, the scroll position, the text in form fields, and an image of each canvas the browser allows it to read. The app accepts messages only from the frame it made, by checking the message’s origin and source.
  4. The app sends the version, the page’s address, the number and the snapshot to the platform. When the platform built that version, it saved, for each page, a list of which file and line made each numbered part. That list never leaves the server. The platform accepts the number only if it is on the list for that page of that version, and only if the platform served that page on the frame’s hostname. The list gives the file and line, and the data file, record and field where data filled it in.
  5. The platform’s own browser opens the snapshot, not a fresh copy of the page, with the site’s scripts turned off so they cannot close what Dana opened, at the same screen size and scroll position, and takes a picture with the part drawn round. So an open menu, a chosen tab and the weather Dana saw all show as they were. The request labels the picture “Rebuilt from what Dana’s browser showed”, because it is not a picture of Dana’s own screen: a browser lets a page take that only after asking the person each time. A 3D scene or other canvas the browser does not let a script read shows as a grey box, and the request says so.

What the request names, for each kind of part:

Dana points at The request names
Text in a page, such as the About page about.html, line 6
A menu label, printed from the site’s English strings file locales/en.json, the string named menu.about, through _includes/header.html, line 5
The weather The weather source and its temperature field, through the {% live %} tag in index.html
Text a script wrote, or a 3D scene The closest enclosing part that has a number, the script files the page loads, and the rebuilt picture

If the file has changed since the version Dana saw, ws requests says so and shows the old text, so the agent works from what Dana saw.

The site’s own scripts run in the same frame as pick.js. A script could stop the taps from reaching the tools, or send the app a wrong number or a changed snapshot. A wrong number can only name another part of a page Dana opened in that version, and the request shows the part it names beside the picture and Dana’s words, so the agent can see a mismatch. The frame design accepts this so that pages keep their scripts running while the owner points.

ws preview --watch follows Shopify’s shopify theme dev, with the update sent from the platform instead of the builder’s computer, so phones get it too.

  1. ws watches the folder for saved files. After a save it waits about 200 milliseconds for more, then sends only the changed files.
  2. The platform rebuilds the pages those files affect, as a new build of the preview.
  3. Each preview has one Durable Object, which holds a WebSocket connection to every browser that has the preview open. The preview-only script in each page opens that connection. Visitors to a published site never get the script.
  4. The Durable Object sends each browser “build 14 is ready, and these files changed”. A browser whose only changed file is a style sheet swaps that style sheet in place. Any other change reloads the page and puts back its scroll position.

The connection checks the same preview cookie as every other request on that hostname, so a browser that lost access to the preview gets no updates.

  • A version holds every file and the site’s settings. These include the display name, subdomain, languages and time zone. They also include whether changes need approval, the connected live sources and the engine release that builds the site. Secrets, such as the token Google gives when an owner connects their Google account, are kept apart. The version holds only an ID that points at the secret. If a live source is now disconnected, rollback shows the fallback text the builder wrote for that part.
  • Outside versions, on purpose: form entries, where form entries are emailed, live data, visit counts, the domain and its DNS, billing, and who may work on the site. Undo and rollback keep the current email recipient. They never lose a form entry or bring back old weather.
  • Saving a version is one step. Each site has one Durable Object, the platform’s single record for that site. Each builder’s folder records the version it was last brought up to date with. The Durable Object saves the folder’s new version only if the version the folder recorded is still the newest, and publishes it in the same step. When it is not, the push is refused, and the builder runs git pull and pushes again. Each publish carries an ID from ws, so a retry after a lost response returns the first result.
  • Samples publish as soon as a version is saved. Checks run in the background, including after undo, rollback and settings changes. Bought sites wait for the checks to pass, even before a domain is attached.
  • Approval is chosen, not required. A builder can send one change to the owner with ws push --needs-approval, or a site can be set so every change waits. The change is kept apart from the versions. When the owner approves it, the Durable Object applies it as a patch to the newest version, in the same step that publishes the result. It is refused only if the same field changed since: a field of a data record, a string in a locales file, or one language’s part of a {% text %} block. A file with no fields, such as an HTML page or a style sheet, counts as one field. So a change waiting for approval never holds up other publishing. This is the architecture document’s approval design.

The platform records, for each translated line, who last wrote it and the main-language text it was written from. A translated line is a string in a locales file (a short text such as a heading, with a name), one language’s part of a {% text %} block (the tag that holds a page’s longer writing, with a part per language), or a translated field of a data record. When the owner corrects a line in their side-by-side view, the line is marked as the owner’s. A later publish that would replace a marked line is refused, naming it. When the main-language text a marked line was written from changes, the owner’s view marks the line for them to look at again. The builder’s agent never changes it.

  • Platform parts are shared. Forms, live data and pick.js are served from /_ws/ on every site. A fix reaches every site in one deploy, with no site rebuilt. The design sends each deploy to 1% of sites, then 10%, then all, with Cloudflare’s gradual deployments, and a rise in errors or a failed form test stops it and puts back the previous release. That staged rollout is not built yet: today each deploy reaches every site at once, and staff can roll a Worker back. Forms built for an older release keep working.
  • Common libraries are shared but fixed. A site loads a library from a path that names its release, such as /_ws/lib/three@0.181.0/three.module.js. The file at that path never changes. Moving sites to a new library release is a batch run: an agent changes the path in each site, makes a version, and the checks below run on it.
  • Each version records the engine release that builds it, and the parts that show live data use the same release. The platform keeps every engine release that a published version uses. A new engine release builds each site’s published version in batches of 1%, 10% and then the rest. A site moves to the new release only when its pages pass the checks below and their text and links come out the same. Any failure stops the batch, and the site stays on its old release.

The platform runs these checks on the built pages in a browser with the site’s own scripts running. They come from the platform’s architecture document: speed (Largest Contentful Paint, the time until the biggest image or block of text on the first screen shows, under 2.5 seconds, with 1.0 second and a Lighthouse score of 100 as the aims), accessibility (WCAG 2.2 AA with axe), links, a test entry through every form, saved as a visitor’s would be, no missing translation, screenshots at 390, 820 and 1440 pixels wide, and no new errors in the browser’s console. A failed check stops a bought site’s publish and ws push names the problem. A sample stays live and ws status reports its newest version’s result. Screenshots are the one exception. They are kept with the version for people to look at, and nothing passes or fails on them. The speed aims of 1.0 second and a Lighthouse score of 100 are shown as results, while the 2.5-second limit is a check. Lighthouse measures home and one page of each layout; every other page gets a quicker load on the same slow phone, and Lighthouse too if that load reaches 2.5 seconds.

The build targets are a 20-page site built in under 10 seconds, and a preview updated in under 5. The staging time for a 20-page publish is still a launch check, so these targets are not yet measured. Lines such as “Built 8 pages.” in the guide’s examples are examples, not measurements.

Why each page is written once for every language

Section titled “Why each page is written once for every language”

An earlier draft of the guide gave each language its own copy of every page, with its own HTML and Liquid. Two copies of the same code drift apart over time. The best-known tools keep one copy of the code and translate the words:

  • Shopify themes keep their strings in locales/ files read with t. A merchant translates their own content in Shopify’s admin, and every language shares the theme’s templates.
  • Hugo shares its templates between languages, keeps strings in one file per language in an i18n folder, and has the writing for each language in its own content files.
  • Eleventy keeps the writing for each language in its own folder, with shared layouts, and needs another library for strings.

This design follows Shopify for strings. It keeps longer writing inside the page, beside the English, so a builder sees both languages in one file and cannot forget one.