@frontlit/preview 0.0.0-stage → 0.1.0-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FrontLit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,136 @@
-# Temporary Holding Version
+# @frontlit/preview
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+See your FrontLit pages in the browser while you edit them.
+
+If your website's pages live in a Git repository as JSON files (a `frontlit/` folder with `pages/*.json` and `site.json`), this tool shows them on your computer the way FrontLit draws them: same blocks, theme, fonts, header and footer. Save a file and the browser updates by itself. You don't need a FrontLit account, a login or an internet connection to your site.
+
+## Before you start
+
+You need [Node.js](https://nodejs.org) **20.19 or newer** (22.12+ also works). Check with:
+
+```sh
+node --version
+```
+
+## Quick start
+
+1. Open a terminal in your repository (the folder that contains `frontlit/`).
+2. Run:
+
+   ```sh
+   npx @frontlit/preview@alpha
+   ```
+
+   The first run downloads the tool, which takes a few seconds.
+3. Open **http://127.0.0.1:4310** in your browser.
+4. Edit any file in `frontlit/` and save. The page reloads with your change.
+
+Press **Ctrl+C** in the terminal to stop.
+
+> **Why `@alpha`?** The tool is in early release. `@alpha` always gets the newest version.
+
+## Using the preview
+
+- **Switch pages** with the drop-down at the top. Each file in `pages/` is one page: `index.json` is `/`, `pricing.json` is `/pricing`. Pages marked `"published": false` show too, so you can check drafts.
+- **Light and dark mode:** use the button in the top bar.
+- **Phone and tablet sizes:** use your browser's device mode (in Chrome: right-click → *Inspect* → the phone icon, then pick a width such as 390 px).
+- **Mistakes are fine.** If a file has invalid JSON or a setting FrontLit doesn't accept, the page shows the error instead. Fix it, save, and the page comes back.
+
+## Show your site name and logo
+
+The header shows "Local preview" until you tell the tool your site's name. Your name and logo are stored in your FrontLit settings rather than the repository, so the tool can't find them alone.
+
+Create `frontlit/preview.context.json`:
+
+```json
+{
+  "branding": {
+    "title": "Acme",
+    "subtitle": "Invoices that chase themselves",
+    "logo": { "url": "assets/logo.svg", "alt": "Acme" }
+  }
+}
+```
+
+- `title` is your site name, the same one set in FrontLit.
+- `subtitle` and `logo` are optional. The logo path is relative to this file, so `assets/logo.svg` means `frontlit/assets/logo.svg`.
+
+This file is only for your computer. Add it to `.gitignore` so it isn't committed:
+
+```sh
+echo "frontlit/preview.context.json" >> .gitignore
+```
+
+### Optional: sample posts for blog-style pages
+
+Pages with a content feed (for example a blog listing) normally show articles from FrontLit. Locally they show a placeholder box. To see real-looking entries, add sample items for that page's address to the same file:
+
+```json
+{
+  "branding": { "title": "Acme" },
+  "feeds": {
+    "/blog": [
+      { "title": "Our first post", "href": "/", "description": "A short summary." }
+    ]
+  }
+}
+```
+
+## Options
+
+```sh
+npx @frontlit/preview@alpha [site-folder] [--port <number>] [--context <file>]
+```
+
+| Option | What it does | Default |
+| --- | --- | --- |
+| `site-folder` | The folder that has `pages/` in it. Use `.` if your pages are at the repository root. | `frontlit` |
+| `--port` | Serve on another port, if 4310 is busy. | `4310` |
+| `--context` | Use a branding file from somewhere else. | `<site-folder>/preview.context.json` |
+| `--help` | Print the usage line. | |
+
+Example: `npx @frontlit/preview@alpha website --port 5000`.
+
+## Images
+
+Put images in your repository (for example `frontlit/assets/`) and point to them from page JSON:
+
+- **Relative paths** start from the JSON file: from `pages/index.json`, use `../assets/hero.webp`.
+- **Paths starting with `/`** start from the repository root: `/frontlit/assets/hero.webp`.
+- **`https://` links** load from the web as usual.
+
+Only image files inside your repository are shown (`.png`, `.jpg`, `.jpeg`, `.webp`, `.avif`, `.gif`, `.svg`).
+
+**Embed snippets are different.** The tool doesn't change URLs written inside an embed's HTML. Use a full `https://` URL there, or `/__frontlit/assets/frontlit/assets/<file>` for an image in your repository.
+
+## What it doesn't show
+
+This tool shows your pages, not everything your live site does:
+
+- Blog posts, docs pages and other content stored in FrontLit (only the pages in `pages/` exist)
+- Redirects from `site.json`
+- Search and the chat assistant
+- Real form submissions: forms only show their success message
+- FrontLit's production image optimization
+
+Before you publish, open your pull request on GitHub and check the **FrontLit / pages preview** link. That's the real thing, built the same way as your live site.
+
+## Troubleshooting
+
+| Message or problem | Fix |
+| --- | --- |
+| `No pages directory in …` | Run the command from your repository, or pass the folder that contains `pages/`, e.g. `npx @frontlit/preview@alpha website`. |
+| Port 4310 already in use | Another preview is probably still running. Stop it with Ctrl+C, or use `--port 4311`. |
+| `Page not found` | There is no `pages/<name>.json` for that address. Check the file name. Names use lowercase letters, numbers and hyphens. |
+| An image doesn't show | Check the path is relative to the JSON file, and that the file is inside the repository and is an image. |
+| The header says "Local preview" | Add `preview.context.json` with your site name (see above). |
+| `Unsupported engine` or a syntax error on start | Update Node.js to 20.19 or newer. |
+
+## For FrontLit contributors
+
+The package ships its CLI (`cli.mjs`), server (`server.mjs`, `site.mjs`) and Vite client (`client/`) as source, so it has no build step. It renders with `@frontlit/page-builder`'s client renderer, `schema` and `theme` entry points.
+
+- Run from the monorepo: build `@frontlit/text-editor` and `@frontlit/page-builder`, then `bun packages/preview/cli.mjs <site-folder>`.
+- Tests: `bun run --cwd packages/preview test`.
+- Once installed from npm, the client runs from `node_modules`. The server therefore pre-bundles the JSX runtime and allows page-builder's package folder for its fonts. Test packaging changes from a packed tarball: `bun pm pack`, then `npm install <tarball>` in an empty folder. A workspace run alone isn't enough.
+- The context file can also hold `site` (the same shape as `site.json`; `site.json` values win) and `themeId` (a bundled theme preset, used when there is no theme object).

package/cli.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { startPreview } from "./server.mjs";
+const usage =
+  "Usage: frontlit-preview [site-folder] [--port 4310] [--context snapshot.json]";
+try {
+  let folder,
+    port = 4310,
+    context;
+  const args = process.argv.slice(2);
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(usage);
+    process.exit(0);
+  }
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--port") {
+      port = Number(args[++i]);
+      if (!Number.isInteger(port) || port < 1 || port > 65535)
+        throw new Error("Invalid port");
+    } else if (args[i] === "--context") {
+      context = args[++i];
+      if (!context || context.startsWith("--"))
+        throw new Error("--context requires a file");
+    } else if (args[i].startsWith("-") || folder) throw new Error(usage);
+    else folder = args[i];
+  }
+  const server = await startPreview(folder ?? "frontlit", { port, context });
+  console.log(`FrontLit local preview — ${folder ?? "frontlit"}`);
+  server.printUrls();
+  for (const signal of ["SIGINT", "SIGTERM"])
+    process.once(signal, async () => {
+      await server.close();
+      process.exit(0);
+    });
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}

package/client/index.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html>
+
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta name="robots" content="noindex,nofollow">
+    <title>FrontLit preview</title>
+</head>
+
+<body>
+    <div id="root"></div>
+    <script type="module" src="/main.jsx"></script>
+</body>
+
+</html>

package/client/main.jsx

@@ -0,0 +1,93 @@
+import React, { useState } from "react";
+import { createRoot } from "react-dom/client";
+import { PageRenderer } from "@frontlit/page-builder/renderer";
+import { resolveTheme } from "@frontlit/page-builder/theme";
+import "@frontlit/page-builder/styles.css";
+import "./preview.css";
+
+function App({ data }) {
+  const [mode, setMode] = useState(
+    localStorage.getItem("frontlit-preview-mode") ?? "light",
+  );
+  if (data.error)
+    return (
+      <main className="preview-error">
+        <h1>Cannot render this page</h1>
+        <pre>{data.error}</pre>
+        <p>Fix the source file; the preview will reload.</p>
+        <a href="/">Home</a>
+      </main>
+    );
+  const theme = resolveTheme(data.themeId, data.themeStyle);
+  const change = (next) => {
+    const resolved =
+      next === "system"
+        ? matchMedia("(prefers-color-scheme: dark)").matches
+          ? "dark"
+          : "light"
+        : next;
+    localStorage.setItem("frontlit-preview-mode", resolved);
+    setMode(resolved);
+  };
+  const fixtures = data.feeds[location.pathname.replace(/\/$/, "") || "/"];
+  const slots = {
+    "content-feed": (
+      <section className="preview-feed">
+        <h2>{fixtures ? "Local feed fixture" : "Content feed — no local fixture"}</h2>
+        {fixtures?.map((entry, i) => (
+          <article key={i}>
+            <a href={entry.href}>{entry.title}</a>
+            <p>{entry.description}</p>
+          </article>
+        ))}
+        {!fixtures && (
+          <p>
+            Add this route to feeds in preview.context.json. FrontLit-hosted content is
+            not fetched automatically.
+          </p>
+        )}
+      </section>
+    ),
+  };
+  return (
+    <>
+      <nav className="preview-toolbar" aria-label="Local preview controls">
+        <strong>Local preview</strong>
+        <select
+          aria-label="Page"
+          value={location.pathname}
+          onChange={(e) => location.assign(e.target.value)}
+        >
+          {data.pages.map((p) => (
+            <option key={p.path} value={p.path}>
+              {p.name}
+            </option>
+          ))}
+        </select>
+        <button onClick={() => change(mode === "light" ? "dark" : "light")}>
+          {mode === "light" ? "Dark" : "Light"} mode
+        </button>
+        {data.missingBranding && <span>Set branding in preview.context.json</span>}
+      </nav>
+      <PageRenderer
+        layout={data.layout}
+        theme={theme}
+        pageData={data.pageData}
+        dataSlots={slots}
+        nextTheme={mode}
+        onThemeModeChange={change}
+      />
+    </>
+  );
+}
+fetch("/__frontlit/data?path=" + encodeURIComponent(location.pathname))
+  .then((r) => r.json())
+  .then((data) => {
+    document.title = (data.title ?? "FrontLit") + " · local preview";
+    createRoot(document.getElementById("root")).render(<App data={data} />);
+  })
+  .catch((error) => {
+    createRoot(document.getElementById("root")).render(
+      <App data={{ error: error.message }} />,
+    );
+  });

package/client/preview.css

@@ -0,0 +1,45 @@
+html,
+body,
+#root {
+  margin: 0;
+  min-height: 100%;
+}
+.preview-toolbar {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 10px 16px;
+  flex-wrap: wrap;
+  background: #fff;
+  color: #18181b;
+  border-bottom: 1px solid #ddd;
+  font:
+    13px system-ui,
+    sans-serif;
+}
+.preview-toolbar button,
+.preview-toolbar select {
+  padding: 6px 10px;
+  border: 1px solid #aaa;
+  border-radius: 4px;
+  background: white;
+  color: #18181b;
+}
+.preview-error {
+  padding: 24px;
+  font:
+    16px system-ui,
+    sans-serif;
+}
+.preview-error pre {
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+.preview-feed {
+  margin: 24px;
+  padding: 24px;
+  border: 1px dashed currentColor;
+}
+.preview-feed a {
+  text-decoration: underline;
+}

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@frontlit/preview",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-alpha.2",
+  "description": "Local, file-watching previews for FrontLit page JSON",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "frontlit-preview": "cli.mjs"
+  },
+  "files": [
+    "cli.mjs",
+    "server.mjs",
+    "site.mjs",
+    "client",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/codelitdev/frontlit.git",
+    "directory": "packages/preview"
+  },
+  "scripts": {
+    "test": "node --test *.test.mjs",
+    "check-types": "node --check cli.mjs && node --check server.mjs && node --check site.mjs"
+  },
+  "dependencies": {
+    "@frontlit/page-builder": "0.1.0-alpha.4",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "vite": "^7.3.6"
+  }
+}

package/server.mjs

@@ -0,0 +1,115 @@
+import { createServer, searchForWorkspaceRoot } from "vite";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+import { existsSync, createReadStream } from "node:fs";
+import { loadSite, localAsset, repositoryRoot } from "./site.mjs";
+
+export async function startPreview(folder, { port = 4310, context } = {}) {
+  folder = resolve(folder);
+  if (!existsSync(join(folder, "pages")))
+    throw new Error(`No pages directory in ${folder}`);
+  const packageRoot = dirname(fileURLToPath(import.meta.url));
+  const root = repositoryRoot(folder);
+  const contextFile = context ? resolve(context) : join(folder, "preview.context.json");
+  if (context && !existsSync(contextFile))
+    throw new Error(`Context file not found: ${contextFile}`);
+  const server = await createServer({
+    configFile: false,
+    envFile: false,
+    root: join(packageRoot, "client"),
+    appType: "spa",
+    resolve: { dedupe: ["react", "react-dom"] },
+    // Installed from npm, the client lives in node_modules, where Vite does not
+    // discover the automatic JSX runtime; it would be served as raw CommonJS.
+    optimizeDeps: { include: ["react/jsx-dev-runtime"] },
+    esbuild: { jsx: "automatic" },
+    server: {
+      host: "127.0.0.1",
+      port,
+      strictPort: true,
+      // Fonts referenced by page-builder's stylesheet live outside this package
+      // when installed from npm.
+      fs: {
+        allow: [
+          searchForWorkspaceRoot(packageRoot),
+          dirname(
+            fileURLToPath(import.meta.resolve("@frontlit/page-builder/styles.css")),
+          ),
+        ],
+      },
+    },
+    plugins: [
+      {
+        name: "frontlit-local-files",
+        configureServer(vite) {
+          vite.watcher.add([folder, contextFile]);
+          let timer;
+          const refresh = (file) => {
+            if (file === contextFile || file.startsWith(folder + "/")) {
+              clearTimeout(timer);
+              timer = setTimeout(() => vite.ws.send({ type: "full-reload" }), 80);
+            }
+          };
+          vite.watcher.on("all", (_, file) => refresh(file));
+          vite.httpServer?.once("close", () => clearTimeout(timer));
+          vite.middlewares.use((req, res, next) => {
+            const url = new URL(req.url, "http://localhost");
+            if (url.pathname === "/__frontlit/data") {
+              res.setHeader("Content-Type", "application/json");
+              res.setHeader("Cache-Control", "no-store");
+              try {
+                res.end(
+                  JSON.stringify(
+                    loadSite(folder, url.searchParams.get("path") ?? "/", contextFile),
+                  ),
+                );
+              } catch (error) {
+                res.statusCode = 400;
+                res.end(JSON.stringify({ error: error.message }));
+              }
+              return;
+            }
+            if (url.pathname.startsWith("/__frontlit/assets/")) {
+              try {
+                const file = localAsset(
+                  root,
+                  decodeURIComponent(url.pathname.slice("/__frontlit/assets/".length)),
+                );
+                const mime = {
+                  ".svg": "image/svg+xml",
+                  ".png": "image/png",
+                  ".jpg": "image/jpeg",
+                  ".jpeg": "image/jpeg",
+                  ".webp": "image/webp",
+                  ".avif": "image/avif",
+                  ".gif": "image/gif",
+                };
+                res.setHeader("Cache-Control", "no-store");
+                res.setHeader(
+                  "Content-Type",
+                  mime[file.slice(file.lastIndexOf(".")).toLowerCase()],
+                );
+                createReadStream(file)
+                  .on("error", () => res.destroy())
+                  .pipe(res);
+              } catch {
+                res.statusCode = 404;
+                res.end("Image not found");
+              }
+              return;
+            }
+            next();
+          });
+        },
+      },
+    ],
+  });
+  try {
+    await server.listen();
+  } catch (error) {
+    // Vite's file watcher would otherwise keep the process alive.
+    await server.close();
+    throw error;
+  }
+  return server;
+}

package/site.mjs

@@ -0,0 +1,145 @@
+import { existsSync, readFileSync, readdirSync, realpathSync } from "node:fs";
+import { dirname, resolve, relative, extname, sep, join } from "node:path";
+import { parsePageFile, parseSiteFile } from "@frontlit/page-builder/schema";
+
+const imageTypes = new Set([".png", ".jpg", ".jpeg", ".webp", ".avif", ".gif", ".svg"]);
+export function repositoryRoot(folder) {
+  for (let dir = folder; ; dir = dirname(dir)) {
+    if (existsSync(join(dir, ".git"))) return dir;
+    if (dirname(dir) === dir) return dirname(folder);
+  }
+}
+export function localAsset(root, path) {
+  const file = realpathSync(resolve(root, path));
+  const rel = relative(realpathSync(root), file);
+  if (
+    rel === ".." ||
+    rel.startsWith(`..${sep}`) ||
+    !imageTypes.has(extname(file).toLowerCase())
+  )
+    throw new Error("Asset must be an image inside the repository.");
+  return file;
+}
+function media(value, owner, root) {
+  if (Array.isArray(value)) return value.map((v) => media(v, owner, root));
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.entries(value).map(([key, v]) => {
+      if (key === "url" && typeof v === "string" && !/^https:\/\//i.test(v)) {
+        const file = localAsset(
+          root,
+          v.startsWith("/") ? v.slice(1) : relative(root, resolve(dirname(owner), v)),
+        );
+        return [
+          key,
+          "/__frontlit/assets/" +
+            relative(root, file).split(sep).map(encodeURIComponent).join("/"),
+        ];
+      }
+      return [key, media(v, owner, root)];
+    }),
+  );
+}
+// The client renders fixtures directly, so reject shapes it would crash on.
+function feedFixtures(feeds, contextFile) {
+  if (feeds === undefined) return {};
+  const fail = (where) => {
+    throw new Error(
+      `${contextFile}: ${where} must be an array of { "title", "href", "description" } strings, keyed by route.`,
+    );
+  };
+  if (!feeds || typeof feeds !== "object" || Array.isArray(feeds)) fail("feeds");
+  for (const [route, entries] of Object.entries(feeds)) {
+    if (!Array.isArray(entries)) fail(`feeds["${route}"]`);
+    entries.forEach((entry, i) => {
+      if (
+        !entry ||
+        typeof entry !== "object" ||
+        Array.isArray(entry) ||
+        ["title", "href", "description"].some(
+          (key) => entry[key] !== undefined && typeof entry[key] !== "string",
+        )
+      )
+        fail(`feeds["${route}"][${i}]`);
+    });
+  }
+  return feeds;
+}
+export function loadSite(
+  folder,
+  pathname = "/",
+  contextFile = join(folder, "preview.context.json"),
+) {
+  const root = repositoryRoot(folder);
+  const slug = decodeURIComponent(pathname).replace(/^\/+|\/+$/g, "");
+  if (slug && !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(slug))
+    throw new Error(
+      `No local page for ${pathname}. Only pages/*.json routes are previewed.`,
+    );
+  const file = join(folder, "pages", `${slug || "index"}.json`);
+  if (!existsSync(file)) throw new Error(`Page not found: ${file}`);
+  const context = existsSync(contextFile)
+    ? JSON.parse(readFileSync(contextFile, "utf8"))
+    : {};
+  const siteFile = join(folder, "site.json");
+  const site = existsSync(siteFile)
+    ? parseSiteFile(readFileSync(siteFile, "utf8"))
+    : {};
+  const fallback = parseSiteFile(context.site ?? {});
+  const effective = { ...fallback, ...site };
+  const page = parsePageFile(readFileSync(file, "utf8"));
+  const instance = (name, settings, index) => ({
+    name,
+    settings,
+    widgetId: `preview-${index}`,
+    shared: name === "header" || name === "footer",
+    deletable: false,
+    moveable: false,
+  });
+  const layout = [
+    instance(
+      "header",
+      media(
+        site.header ?? fallback.header ?? { links: [], ctaLabel: "", ctaHref: "" },
+        site.header ? siteFile : contextFile,
+        root,
+      ),
+      "header",
+    ),
+    ...page.layout.map((b, i) =>
+      instance(b.name, media(b.settings ?? {}, file, root), i),
+    ),
+    instance(
+      "footer",
+      media(
+        site.footer ??
+          fallback.footer ?? { columns: [], tagline: "", copyrightText: "" },
+        site.footer ? siteFile : contextFile,
+        root,
+      ),
+      "footer",
+    ),
+  ];
+  const branding = media(context.branding ?? {}, contextFile, root);
+  return {
+    title: page.title ?? (slug || "Local preview"),
+    layout,
+    themeStyle: effective.theme ?? null,
+    themeId: context.themeId ?? null,
+    pageData: {
+      siteTitle: branding.title ?? "Local preview",
+      siteSubtitle: branding.subtitle ?? null,
+      siteLogoUrl: branding.logo?.url ?? null,
+      siteLogoAlt: branding.logo?.alt ?? null,
+      pageSlug: slug,
+    },
+    pages: readdirSync(join(folder, "pages"))
+      .filter((f) => /^(index|[a-z0-9]+(?:-[a-z0-9]+)*)\.json$/.test(f))
+      .map((f) => ({
+        path: f === "index.json" ? "/" : "/" + f.slice(0, -5),
+        name: f.slice(0, -5),
+      })),
+    feeds: feedFixtures(context.feeds, contextFile),
+    missingBranding: !branding.title,
+  };
+}