mechanica 2.1.0-beta.7 → 2.2.0

package/README.md

@@ -344,25 +344,31 @@ By default all blocks share one `blocks` chunk, cached across pages. Mark heavy,
 ```bash
 npx mechanica shot hero                     # screenshot one block, from its previewData
 npx mechanica shot /about --width 1440,390  # a whole page, at two widths
+npx mechanica shot design/landing/index.html --width 1440,390   # a design handoff, the same way
+npx mechanica shot /about --section "#pricing" --section "footer" # one PNG per section
+npx mechanica shot /about --scroll 800,1600 # the viewport after scrolling (sticky, scroll-driven states)
 npx mechanica thumbs                        # page thumbnails for the editor's page browser
 npx mechanica thumbs --blocks               # block thumbnails for the palette
 ```
 
 These drive a locally installed Chrome or Edge (or `--browser <path>`) and need Node.js 22+ or Bun. They reuse a dev server running on port 5173 and start one if there isn't. Screenshots go to `.mech/shots/`, which is handy for reviewing a block or letting an AI assistant check its own work.
 
+`shot` also takes any `http(s)://` URL, a `file://` URL or a path to a local `.html` file, and renders it with the same browser, widths, waits and animation freeze as your own pages, without a dev server. That lets you compare a design handoff with the page you built from it, section by section: run both with the same `--width` and `--section` flags. `--scroll <px>` scrolls first and captures what is on screen, so sticky stages and scroll-revealed content show their later states. `--no-freeze` leaves animations and transitions running. For your own scripts (for example, measuring computed styles in the design and on the site), `mechanica/browser` exposes the same headless browser (see [API](#api)).
+
 ## CLI
 
 | Command | What it does |
 | --- | --- |
 | `mechanica export` | Build, then render every page to static HTML in `export/`. Flags: `--site-url`, `--site-name`, `--assets-url` (serve `/assets` and `/media` from a CDN) |
 | `mechanica build` | Build the client and server bundles into `dist/` (`export` runs this for you) |
-| `mechanica shot <blockId \| /path>` | Screenshot a block or a page. Flags: `--width`, `--data`, `--out`, `--full`, `--server`, `--browser` |
+| `mechanica shot <blockId \| /path \| url \| file.html>` | Screenshot a block, a page, any URL or a local HTML file (a design handoff; no dev server needed). Flags: `--width`, `--section <css>` (repeatable, one PNG each), `--scroll <px[,px…]>` (the viewport after scrolling), `--no-freeze`, `--full`, `--data` (blocks), `--out`, `--server`, `--browser` |
 | `mechanica thumbs [--blocks]` | Regenerate page or block thumbnails for the editor |
 | `mechanica images` | Generate image dimensions and blur-up previews for `.mech/assets` (needs `sharp`; `--force` redoes all) |
-| `mechanica login` | Sign in to the Mechanica platform and save an access token for this machine (`--host`, `--token`) |
+| `mechanica login` | Sign in to the Mechanica platform: it prints a link to open and approve in the browser (signing in or registering on the way) and keeps the access token for this machine. In a terminal it waits for the approval; run from a coding agent, it prints the link and returns, and the next `link` or `push` finishes the sign-in (`--wait`, `--no-wait`, `--host`, or `--token` to store a token made in the dashboard) |
 | `mechanica link <slug>` | Point this repository at a site on the platform (`--create` makes the site); uploads are then kept by the platform, so `.mech/assets/` goes into `.gitignore` |
 | `mechanica push` | Publish the committed project to the platform: pull what was edited online, send the uploads it lacks, `git push`, build and upload the bundle when the code changed, wait for the deploy. It pushes the branch that is checked out, under its own name: the first branch a site is pushed is the site itself, any other is deployed to an address of its own (`<slug>--<branch>`) with its own online editor — a branch name is lowercase letters, digits and single hyphens |
 | `mechanica assets pull` | Download the uploads made in the platform's online editor that this project lacks (the dev server fetches them one by one on demand) |
+| `mechanica migrate` | Bring `.mech` content written by an older version up to the current format: uploads are addressed as `/media/<file>` (2.0 wrote `/@mechanica/assets/<file>`) |
 
 ## Plugin options
 
@@ -393,6 +399,27 @@ From `mechanica`:
 
 From `mechanica/plugin`: `mechanica` and the `PageProvider` type. From `mechanica/widgets`: `defineWidget` and `useWidgetServices` (uploads and the image picker inside widget editors). `mechanica/editor` and `mechanica/composer` are loaded by the plugin in development; you don't import them. From `mechanica/export`: `exportBuilt(projectDir, options)`, which statically renders an already built project (`dist/` + `.mech/`) without running a build and resolves to `{ pages, warnings }` — for render services that receive a prebuilt bundle; `options.outDir` sets where the site is written, and `options.fetchJson` replaces how `useFetch` requests are made.
 
+From `mechanica/browser`: the headless browser behind `mechanica shot`, for your own Node 22+ or Bun scripts. It needs no dev server and no Vite. `openPage(url, { width, height, browser })` launches a local Chrome or Edge and resolves to a page with `evaluate(expression)`, `setViewport(width, height)`, `scrollTo(y)`, `settle()` (fonts and images), `freezeAnimations()`, `sectionClip(selector)`, `screenshot({ clip, section, full, scale })` (a PNG `Buffer`; with no options, what is in the viewport), `goto(url)`, `messages` (console errors and page errors) and `close()`. `findDevServer()` returns the origin of a running dev server, or `null`.
+
+```js
+import { openPage } from 'mechanica/browser'
+
+const page = await openPage(new URL('design/landing/index.html', import.meta.url).href, { width: 390 })
+try {
+  const size = await page.evaluate(`getComputedStyle(document.querySelector('#hero h1')).fontSize`)
+  await page.scrollTo(1200)
+  const png = await page.screenshot({ section: '#hero' })
+} finally {
+  await page.close()
+}
+```
+
+## Upgrading from 2.0
+
+- Uploaded files are addressed as `/media/<file>` in page files, shared data and rich text; 2.0 wrote `/@mechanica/assets/<file>`. The old address still works everywhere, so nothing breaks — run `npx mechanica migrate` once to rewrite it, and don't serve anything of your own under `/media/`.
+- A file uploaded through the editor now gets a short content hash in its name (`photo-9f2c1a7b.jpg`). Files already in `.mech/assets/` keep their names.
+- In the page browser, "Mark as draft" / "Publish" became "Hide from site" / "Show on site". `draft: true` in the page file means the same as before.
+
 ## Upgrading from 1.x
 
 Mechanica 2 is a rewrite, and a 1.x project has to be ported by hand; there is no automatic migration. What changes:

package/dist/browser.js

@@ -0,0 +1,2 @@
+import { a as MAX_SHOT_HEIGHT, i as openPage, n as PAGE_LOADED, o as findDevServer, r as describeSectionError, t as NavigationError } from "./chunks/browser-BCfAv8bW.js";
+export { MAX_SHOT_HEIGHT, NavigationError, PAGE_LOADED, describeSectionError, findDevServer, openPage };

package/dist/chunks/{assets-nujjbCx8.js → assets-5a2WdmFg.js}

@@ -1,44 +1,8 @@
-import { G as isAssetName, J as readImageManifest, X as updateImageManifest } from "./rich-text-codec-BSD35k2U.js";
+import { G as isAssetName, J as readImageManifest, X as updateImageManifest } from "./rich-text-codec-DCv1X0eZ.js";
 import { join } from "node:path";
-import { chmod, mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { chmod, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
 import os from "node:os";
 import { spawn } from "node:child_process";
-/** Normalize a host argument to an origin (`https://example.com`, no trailing slash or path). */
-function hostOrigin(host) {
-	const value = host ?? process.env.MECHANICA_HOST ?? "https://mechanica.jt3.ru";
-	return new URL(/^https?:\/\//.test(value) ? value : `https://${value}`).origin;
-}
-/** Where access tokens are kept: one file per user, outside any project. */
-function credentialsFile() {
-	return join(process.env.MECHANICA_CONFIG_DIR ?? join(os.homedir(), ".mechanica"), "credentials.json");
-}
-async function readAll() {
-	try {
-		const parsed = JSON.parse(await readFile(credentialsFile(), "utf-8"));
-		return parsed && typeof parsed === "object" ? parsed : {};
-	} catch {
-		return {};
-	}
-}
-/**
-* The access token for a platform origin: `MECHANICA_TOKEN` (CI) wins over the
-* one `mechanica login` saved.
-*/
-async function getToken(origin) {
-	if (process.env.MECHANICA_TOKEN) return process.env.MECHANICA_TOKEN;
-	return (await readAll())[origin] ?? null;
-}
-/** Remember the token for an origin, in a file only the user can read. */
-async function saveToken(origin, token) {
-	const file = credentialsFile();
-	const all = await readAll();
-	all[origin] = token;
-	await mkdir(join(file, ".."), { recursive: true });
-	await writeFile(file, JSON.stringify(all, null, 2) + "\n", { mode: 384 });
-	await chmod(file, 384).catch(() => {});
-	return file;
-}
-//#endregion
 //#region src/cli/platform/api.ts
 /** A failed platform request: the HTTP status plus the message the platform gave. */
 var PlatformError = class extends Error {
@@ -80,12 +44,6 @@ async function request(origin, method, path, options = {}) {
 	if (!response.ok) throw new PlatformError(response.status, errorMessage(response.status, text));
 	return text ? JSON.parse(text) : null;
 }
-/** The saved token for `origin`, or an error telling the user to log in. */
-async function requireToken(origin) {
-	const token = await getToken(origin);
-	if (!token) throw new Error(`Not logged in to ${origin} — run \`mechanica login\` first`);
-	return token;
-}
 /** The name of the git remote `mechanica link` manages. */
 var REMOTE_NAME = "mechanica";
 /**
@@ -105,6 +63,70 @@ function parseRemoteUrl(url) {
 		return null;
 	}
 }
+/** Normalize a host argument to an origin (`https://example.com`, no trailing slash or path). */
+function hostOrigin(host) {
+	const value = host ?? process.env.MECHANICA_HOST ?? "https://mechanica.jt3.ru";
+	return new URL(/^https?:\/\//.test(value) ? value : `https://${value}`).origin;
+}
+/** Where the CLI keeps what it knows about the user: one folder per user, outside any project. */
+function configDir() {
+	return process.env.MECHANICA_CONFIG_DIR ?? join(os.homedir(), ".mechanica");
+}
+/** Access tokens, by platform origin. */
+var credentialsFile = () => join(configDir(), "credentials.json");
+/** Sign-ins started by `mechanica login` that wait for their approval, by platform origin. */
+var pendingFile = () => join(configDir(), "pending-logins.json");
+async function readJson(file) {
+	try {
+		const parsed = JSON.parse(await readFile(file, "utf-8"));
+		return parsed && typeof parsed === "object" ? parsed : {};
+	} catch {
+		return {};
+	}
+}
+/** Write one of the files, readable by the user alone. */
+async function writeJson(file, value) {
+	await mkdir(join(file, ".."), { recursive: true });
+	await writeFile(file, JSON.stringify(value, null, 2) + "\n", { mode: 384 });
+	await chmod(file, 384).catch(() => {});
+}
+/**
+* The access token for a platform origin: `MECHANICA_TOKEN` (CI) wins over the
+* one `mechanica login` saved.
+*/
+async function getToken(origin) {
+	if (process.env.MECHANICA_TOKEN) return process.env.MECHANICA_TOKEN;
+	return (await readJson(credentialsFile()))[origin] ?? null;
+}
+/** Remember the token for an origin, in a file only the user can read. */
+async function saveToken(origin, token) {
+	const file = credentialsFile();
+	const all = await readJson(file);
+	all[origin] = token;
+	await writeJson(file, all);
+	return file;
+}
+/** The sign-in waiting for an origin, or null. An expired one is reported too: whoever reads it says so. */
+async function getPendingLogin(origin) {
+	const entry = (await readJson(pendingFile()))[origin];
+	return entry && typeof entry.deviceCode === "string" && typeof entry.verificationUrl === "string" ? entry : null;
+}
+/** Keep a started sign-in for an origin (replacing an earlier one). */
+async function savePendingLogin(origin, login) {
+	const file = pendingFile();
+	const all = await readJson(file);
+	all[origin] = login;
+	await writeJson(file, all);
+}
+/** Forget the sign-in waiting for an origin — it was finished, denied or has expired. */
+async function clearPendingLogin(origin) {
+	const file = pendingFile();
+	const all = await readJson(file);
+	if (!(origin in all)) return;
+	delete all[origin];
+	if (Object.keys(all).length) await writeJson(file, all);
+	else await rm(file, { force: true });
+}
 //#endregion
 //#region src/cli/platform/git.ts
 /**
@@ -319,4 +341,4 @@ async function runAssetsPull(options = {}) {
 	return done;
 }
 //#endregion
-export { git as a, PlatformError as c, request as d, requireToken as f, uploadsIgnored as i, REMOTE_NAME as l, saveToken as m, remoteAssetsFor as n, gitAuthEnv as o, hostOrigin as p, runAssetsPull as r, gitOk as s, pushUploads as t, parseRemoteUrl as u };
+export { request as _, git as a, clearPendingLogin as c, hostOrigin as d, savePendingLogin as f, parseRemoteUrl as g, REMOTE_NAME as h, uploadsIgnored as i, getPendingLogin as l, PlatformError as m, remoteAssetsFor as n, gitAuthEnv as o, saveToken as p, runAssetsPull as r, gitOk as s, pushUploads as t, getToken as u };