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

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,40 @@
-# 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.
+Read-only local previews of FrontLit repository pages using the existing page-builder React renderer, compiled styles, fonts and shadow-root embeds. Node 20.19+ (or 22.12+) is required.
+
+After publication:
+
+```sh
+npx @frontlit/preview ./frontlit
+npx @frontlit/preview ./frontlit --port 4311 --context ./preview.context.json
+```
+
+In the monorepo, build `@frontlit/text-editor` and `@frontlit/page-builder`, then run `bun packages/preview/cli.mjs <site-folder>`. The default address is http://127.0.0.1:4310. Changes to page JSON, site JSON, images or context refresh the browser. Invalid files display diagnostics and recover on the next edit. Use the toolbar to select pages or switch color mode; browser device emulation works normally.
+
+The site folder contains `pages/*.json` and optional `site.json`. Shared chrome and theme come from `site.json`. Missing values can fall back to a local context file (`preview.context.json` in the site folder, or `--context`). Branding lives outside FrontLit's Git site format, so provide it explicitly:
+
+```json
+{
+  "branding": {
+    "title": "John's Piping Pizza",
+    "subtitle": "Dough. Heat. Repeat.",
+    "logo": { "url": "assets/logo.svg", "alt": "John's Piping Pizza" }
+  },
+  "site": {},
+  "feeds": {
+    "/blog": [
+      { "title": "Our pizza notebook", "href": "/", "description": "A local feed fixture." }
+    ]
+  }
+}
+```
+
+`site` accepts the same chrome/theme structure as `site.json`; local site fields win. An optional `themeId` selects a bundled preset when there is no theme object. This is a local snapshot, not an authenticated export endpoint. No FrontLit credentials or backend are required. Use a gitignored context file for private fixture data.
+
+Repository images resolve relative to their owning JSON file, or relative to the repository root for paths starting with `/`. Only image files inside that root are served through the asset endpoint, including symlink checks. Without a Git root, the site folder's parent is the root. HTTPS media remains remote. URLs inside raw embed HTML are not rewritten; use a permanent HTTPS URL or the local asset URL (`/__frontlit/assets/<repository-relative-path>`).
+
+Page routes correspond to `pages/*.json`. Draft pages are deliberately previewable. Backend article/doc detail routes, redirects, chatbot, search and production image optimization are not implemented. Feeds use explicit local fixtures or a visible placeholder; forms receive no team/API identity and use page-builder's local success behavior. This previews the client renderer; the hosted site uses server rendering, so the release preview remains the final integration check. Keep the renderer dependency aligned with the release being targeted.
+
+The package ships its Vite client and CLI as source and needs no separate build. `bun run --cwd packages/preview test` checks normalization, local media boundaries and missing/invalid input behavior.
+
+Release prerequisite: the renderer dependency must include its existing `schema` and `theme` entry points (the current workspace alpha.2); the older npm alpha.1 does not export them. Publish compatible workspace dependencies before this utility. No page-builder implementation changes are needed.

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.1",
+  "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.3",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "vite": "^7.3.6"
+  }
+}

package/server.mjs

@@ -0,0 +1,107 @@
+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();
+          });
+        },
+      },
+    ],
+  });
+  await server.listen();
+  return server;
+}

package/site.mjs

@@ -0,0 +1,120 @@
+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)];
+    }),
+  );
+}
+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: context.feeds ?? {},
+    missingBranding: !branding.title,
+  };
+}