@picloom/create-theme 0.0.0-stage → 0.1.0

package/dist/template/dev/main.ts

@@ -0,0 +1,179 @@
+import { manifest, config, production } from "virtual:picloom-preview";
+import { createPreview, scenarios, type Scenario } from "./context";
+import type { Page, ThemeModule } from "@picloom/theme-sdk";
+const root = document.getElementById("app")!;
+let instance: { dispose(): void } | undefined,
+  generation = 0;
+const sourceModule = production ? "/entry.js" : "/src/entry.ts";
+const runtime = createPreview(manifest, config, navigate);
+const preview = document.createElement("aside");
+preview.id = "picloom-preview-tools";
+const shadow = preview.attachShadow({ mode: "open" });
+shadow.innerHTML = `<style>:host{position:fixed;right:12px;bottom:12px;z-index:2147483647;font:13px system-ui;color:#eee}details{background:#15212e;border:1px solid #617080;border-radius:10px;padding:12px;max-width:300px;box-shadow:0 4px 20px #0005}summary{cursor:pointer;font-weight:bold}label{display:grid;gap:4px;margin-top:10px}select{background:#fff;color:#17212c;padding:5px;min-width:220px}p{max-width:260px;font-size:12px}output{display:block;color:#ffd37c;white-space:pre-wrap;overflow-wrap:anywhere}</style>
+<details open><summary>Picloom · Preview / 预览</summary><p>${production ? "Production build / 构建产物" : "Source HMR / 源码热更新"}<br>SIMULATED uploads and login<br>模拟上传与登录，不连接真实服务</p>
+<label>Page / 页面<select id="page"><option value="home">Home / 首页</option><option value="login">Login / 登录</option></select></label>
+<label>Language / 语言<select id="language"></select></label>
+<label>Appearance / 外观<select id="mode"><option value="auto">System / 跟随系统</option><option value="light">Light / 浅色</option><option value="dark">Dark / 深色</option></select></label>
+<label>Identity / 身份<select id="identity"><option value="guest">Guest / 访客</option><option value="user">Signed in / 已登录</option></select></label>
+<label>Scenario / 场景<select id="scenario"></select></label><output role="alert"></output></details>`;
+document.body.append(preview);
+const select = (id: string) => shadow.getElementById(id) as HTMLSelectElement;
+const errors = shadow.querySelector("output")!;
+function option(value: string, label: string) {
+  const node = document.createElement("option");
+  node.value = value;
+  node.textContent = label;
+  return node;
+}
+for (const language of runtime.ctx.getSnapshot().languages)
+  select("language").append(option(language.tag, language.name));
+const labels: Record<Scenario, string> = {
+  ready: "Ready / 就绪",
+  loading: "Loading / 加载中",
+  uploading: "Uploading / 上传中",
+  success: "Success / 上传成功",
+  failed: "Failed / 上传失败",
+  "no-profiles": "No profiles / 无可用方案",
+  "login-error": "Login error / 登录失败",
+};
+for (const scenario of scenarios)
+  select("scenario").append(option(scenario, labels[scenario]));
+select("page").onchange = () => navigate(select("page").value as Page);
+select("language").onchange = () =>
+  runtime.ctx.setLocale(select("language").value);
+select("mode").onchange = () =>
+  runtime.ctx.setMode(select("mode").value as "auto" | "light" | "dark");
+select("identity").onchange = () =>
+  runtime.setUser(select("identity").value === "user");
+select("scenario").onchange = () =>
+  runtime.setScenario(select("scenario").value as Scenario);
+const stop = runtime.ctx.subscribe((state) => {
+  select("page").value = state.page;
+  select("language").value = state.locale;
+  select("mode").value = state.mode;
+  select("identity").value = state.user ? "user" : "guest";
+});
+function cleanup() {
+  const previous = instance;
+  instance = undefined;
+  try {
+    previous?.dispose();
+  } catch (error) {
+    errors.textContent = String(error);
+  } finally {
+    root.replaceChildren();
+  }
+}
+async function mount() {
+  const current = ++generation;
+  errors.textContent = "";
+  cleanup();
+  const subscriptions = new Set<() => void>();
+  const links: HTMLLinkElement[] = [];
+  const container = document.createElement("div");
+  root.append(container);
+  let mounted: Awaited<ReturnType<ThemeModule["mount"]>> | undefined;
+  let cleaned = false;
+  const context = {
+    ...runtime.ctx,
+    subscribe(listener: Parameters<typeof runtime.ctx.subscribe>[0]) {
+      // An async mount may continue after its page has already been unmounted.
+      if (cleaned) return () => {};
+      const stop = runtime.ctx.subscribe(listener);
+      subscriptions.add(stop);
+      return () => {
+        stop();
+        subscriptions.delete(stop);
+      };
+    },
+  };
+  const dispose = () => {
+    if (cleaned) return;
+    cleaned = true;
+    try {
+      if (typeof mounted?.dispose === "function") mounted.dispose();
+    } finally {
+      for (const stop of subscriptions) stop();
+      subscriptions.clear();
+      for (const link of links) link.remove();
+      container.remove();
+    }
+  };
+  instance = { dispose };
+  try {
+    const page = runtime.ctx.getSnapshot().page;
+    const declaration = manifest.pages[page];
+    if (!declaration)
+      throw Error(
+        `Theme does not declare ${page}; the real host will use its default page`,
+      );
+    const styles = new Set([
+      ...(manifest.styles ?? []),
+      ...(declaration.styles ?? []),
+    ]);
+    await Promise.all(
+      [...styles]
+        .filter((path) => production || path !== "style.css")
+        .map(
+          (path) =>
+            new Promise<void>((resolve, reject) => {
+              // The source entry imports src/style.css; other declared styles are public assets.
+              const link = document.createElement("link");
+              link.rel = "stylesheet";
+              link.href = runtime.ctx.asset(path);
+              link.onload = () => resolve();
+              link.onerror = () =>
+                reject(Error(`Missing theme style: ${path}`));
+              links.push(link);
+              document.head.append(link);
+            }),
+        ),
+    );
+    if (current !== generation || cleaned) return;
+    const module: ThemeModule = await import(/* @vite-ignore */ sourceModule);
+    if (typeof module.mount !== "function")
+      throw Error("Theme must export mount(container, context)");
+    if (current !== generation || cleaned) return;
+    mounted = await module.mount(container, context);
+    if (!mounted || typeof mounted.dispose !== "function")
+      throw Error("mount() must return { dispose() }");
+    if (current !== generation || cleaned) {
+      if (cleaned) mounted.dispose();
+      else dispose();
+    }
+  } catch (error) {
+    try {
+      dispose();
+    } finally {
+      if (current === generation) errors.textContent = String(error);
+    }
+  }
+}
+function navigate(page: Page) {
+  history.pushState(null, "", page === "login" ? "/login" : "/");
+  runtime.setPage(page);
+  void mount();
+}
+function popstate() {
+  runtime.setPage(location.pathname === "/login" ? "login" : "home");
+  void mount();
+}
+window.addEventListener("popstate", popstate);
+function dispose() {
+  generation++;
+  cleanup();
+  stop();
+  runtime.dispose();
+  preview.remove();
+  window.removeEventListener("popstate", popstate);
+}
+function pagehide(event: PageTransitionEvent) {
+  if (!event.persisted) dispose();
+}
+window.addEventListener("pagehide", pagehide);
+import.meta.hot?.dispose(() => {
+  window.removeEventListener("pagehide", pagehide);
+  dispose();
+});
+// Vue SFC/CSS updates use normal HMR. Entry changes invalidate the importer and reload.
+await mount();

package/dist/template/dev/virtual.d.ts

@@ -0,0 +1,5 @@
+declare module "virtual:picloom-preview" {
+  export const manifest: import("@picloom/theme-sdk").Manifest;
+  export const config: import("@picloom/theme-sdk").Config;
+  export const production: boolean;
+}

package/dist/template/gitignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+.env
+.env.*

package/dist/template/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "my-theme",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "bun": ">=1.4.3"
+  },
+  "scripts": {
+    "dev": "bun scripts/serve.ts",
+    "typecheck": "bun --bun vue-tsc --noEmit",
+    "build": "bun run typecheck && bun scripts/build.ts",
+    "preview": "bun scripts/serve.ts --preview"
+  },
+  "devDependencies": {
+    "@picloom/theme-sdk": "0.1.0",
+    "@tailwindcss/vite": "4.3.3",
+    "@types/bun": "1.3.10",
+    "@vitejs/plugin-vue": "6.0.10",
+    "fflate": "0.8.2",
+    "tailwindcss": "4.3.3",
+    "typescript": "5.9.3",
+    "vite": "8.3.4",
+    "vue": "3.5.44",
+    "vue-tsc": "3.3.13"
+  }
+}

package/dist/template/public/README.txt

@@ -0,0 +1,3 @@
+Put explicit theme assets under assets/ (for example assets/background.webp).
+Only assets/ is packaged; this README is not included in the ZIP.
+主题静态文件请放入 assets/，例如 assets/background.webp。此说明不进入 ZIP。

package/dist/template/scripts/build.ts

@@ -0,0 +1,119 @@
+import {
+  mkdir,
+  readdir,
+  readFile,
+  lstat,
+  writeFile,
+  cp,
+  rm,
+} from "node:fs/promises";
+import { resolve, relative, dirname } from "node:path";
+import { build } from "vite";
+import { zipSync, strToU8 } from "fflate";
+import { assetPath, readManifest } from "./manifest";
+const manifest = await readManifest();
+const output = resolve("dist/package");
+const archive = resolve("dist", `${manifest.id}-${manifest.version}.zip`);
+// A failed build must not leave an older ZIP looking like the new result.
+await rm(archive, { force: true });
+await build();
+async function files(root: string): Promise<string[]> {
+  if ((await lstat(root)).isSymbolicLink())
+    throw Error(`Do not package symbolic links: ${root}`);
+  const result: string[] = [];
+  for (const name of await readdir(root)) {
+    const path = resolve(root, name),
+      stat = await lstat(path);
+    if (stat.isSymbolicLink())
+      throw Error(`Do not package symbolic links: ${path}`);
+    if (stat.isDirectory()) result.push(...(await files(path)));
+    else if (stat.isFile()) result.push(path);
+    else throw Error(`Unsupported file: ${path}`);
+  }
+  return result;
+}
+try {
+  for (const path of await files(resolve("public/assets"))) {
+    const name = relative(resolve("public"), path).replaceAll("\\", "/");
+    if (
+      !assetPath(name) ||
+      /(?:^|\/)\./.test(name) ||
+      /\.(?:map|env|pem|key|ts|vue)$/i.test(name)
+    )
+      throw Error(`Not a distributable theme asset: ${name}`);
+    const destination = resolve(output, name);
+    if (await Bun.file(destination).exists())
+      throw Error(`Asset collides with build output: ${name}`);
+    await mkdir(dirname(destination), { recursive: true });
+    await cp(path, destination);
+  }
+} catch (error) {
+  if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+}
+await cp("LICENSE", output + "/LICENSE");
+const declaration = JSON.stringify(manifest, null, 2) + "\n";
+if (strToU8(declaration).byteLength > 256 * 1024)
+  throw Error("theme.json exceeds 256 KiB");
+await writeFile(output + "/theme.json", declaration);
+const entries: Record<string, Uint8Array> = {};
+const names = new Set<string>();
+let total = 0;
+for (const path of await files(output)) {
+  const name = relative(output, path).replaceAll("\\", "/");
+  if (
+    !assetPath(name) ||
+    names.has(name.toLowerCase()) ||
+    /(?:^|\/)(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|\/|$)/i.test(name) ||
+    /(?:^|\/)\./.test(name) ||
+    name.endsWith(".map")
+  )
+    throw Error(`Invalid or duplicate package path: ${name}`);
+  names.add(name.toLowerCase());
+  const bytes = new Uint8Array(await readFile(path));
+  total += bytes.byteLength;
+  if (total > 50 * 1024 * 1024 || names.size > 512)
+    throw Error("Theme exceeds 50 MiB expanded or 512 files");
+  if (/\.m?js$/.test(name)) {
+    const code = new TextDecoder().decode(bytes);
+    const imports = new Bun.Transpiler({
+      loader: "js",
+      target: "browser",
+    }).scanImports(code);
+    if (imports.length)
+      throw Error(
+        `Unbundled runtime imports in ${name}; this template produces a self-contained entry`,
+      );
+    if (
+      /["'`]\/(?:@vite|@id|@fs|src|dev)\/|localhost:\d|127\.0\.0\.1:\d|\/\/[#@]\s*sourceMappingURL=/.test(
+        code,
+      )
+    )
+      throw Error(`Development reference in ${name}`);
+  }
+  if (
+    name.endsWith(".css") &&
+    /localhost:\d|127\.0\.0\.1:\d|(?:url|@import)\s*\(?["']?\/(?:src|dev|@vite)\//.test(
+      new TextDecoder().decode(bytes),
+    )
+  )
+    throw Error(`Development reference in ${name}`);
+  entries[name] = bytes;
+}
+if (entries["style.css"] && !manifest.styles?.includes("style.css"))
+  throw Error(
+    "The template bundles imported CSS into style.css; declare it in theme.json styles",
+  );
+for (const name of [
+  ...(manifest.styles ?? []),
+  ...(manifest.preview ? [manifest.preview] : []),
+  ...Object.values(manifest.pages).flatMap((page) => [
+    page.entry,
+    ...(page.styles ?? []),
+  ]),
+]) {
+  if (!entries[name]) throw Error(`Missing theme resource: ${name}`);
+}
+const zip = zipSync(entries);
+if (zip.byteLength > 20 * 1024 * 1024) throw Error("Theme ZIP exceeds 20 MiB");
+await Bun.write(archive, zip);
+console.log(archive);

package/dist/template/scripts/manifest.ts

@@ -0,0 +1,61 @@
+import { readFile } from "node:fs/promises";
+import type { Manifest } from "@picloom/theme-sdk";
+import { supportedLocales, safeName, assetPath } from "../dev/helpers.js";
+export { assetPath } from "../dev/helpers.js";
+export async function readManifest(path = "theme.json"): Promise<Manifest> {
+  const value = JSON.parse(await readFile(path, "utf8"));
+  const object = (v: unknown): v is Record<string, any> =>
+    !!v && typeof v === "object" && !Array.isArray(v);
+  if (
+    !object(value) ||
+    !safeName(value.id) ||
+    value.id.startsWith("builtin.") ||
+    !safeName(value.version) ||
+    value.apiVersion !== 1 ||
+    !Array.isArray(value.supportedLocales) ||
+    !value.supportedLocales.length ||
+    value.supportedLocales.some((v: string) => !supportedLocales.includes(v)) ||
+    new Set(value.supportedLocales).size !== value.supportedLocales.length ||
+    !value.supportedLocales.includes(value.defaultLocale) ||
+    !object(value.pages) ||
+    !Object.keys(value.pages).length ||
+    Object.keys(value.pages).some((key) => !["home", "login"].includes(key)) ||
+    !object(value.messages) ||
+    !object(value.messages[value.defaultLocale]) ||
+    typeof value.nameKey !== "string" ||
+    typeof value.messages[value.defaultLocale][value.nameKey] !== "string" ||
+    !value.messages[value.defaultLocale][value.nameKey].trim()
+  )
+    throw Error(
+      "Invalid theme.json: check identity, API, pages and language declarations",
+    );
+  for (const page of Object.values(value.pages) as Array<{
+    entry: string;
+    styles?: string[];
+  }>) {
+    if (!object(page) || page.entry !== "entry.js")
+      throw Error(
+        "This template builds src/entry.ts as entry.js; use that entry for each page",
+      );
+    if (
+      page.styles !== undefined &&
+      (!Array.isArray(page.styles) ||
+        page.styles.some((p) => !assetPath(p) || !p.endsWith(".css")))
+    )
+      throw Error("Invalid page styles");
+  }
+  if (
+    value.styles !== undefined &&
+    (!Array.isArray(value.styles) ||
+      value.styles.some((p: unknown) => !assetPath(p) || !p.endsWith(".css")))
+  )
+    throw Error("Invalid styles");
+  if (
+    value.preview !== undefined &&
+    (!assetPath(value.preview) || !/\.(png|jpe?g|webp)$/i.test(value.preview))
+  )
+    throw Error("Invalid preview image");
+  if (value.configSchema !== undefined && value.configSchema?.type !== "object")
+    throw Error("configSchema must be an object schema");
+  return value as Manifest;
+}

package/dist/template/scripts/serve.ts

@@ -0,0 +1,127 @@
+import { createServer, type Plugin } from "vite";
+import vue from "@vitejs/plugin-vue";
+import tailwindcss from "@tailwindcss/vite";
+import { resolve } from "node:path";
+import { readFile, mkdir, writeFile } from "node:fs/promises";
+import { initialValue } from "../dev/helpers.js";
+import { assetPath, readManifest } from "./manifest";
+const args = process.argv.slice(2),
+  production = args.includes("--preview");
+const portIndex = args.indexOf("--port");
+const port = portIndex === -1 ? 5173 : Number(args[portIndex + 1]);
+if (
+  !Number.isInteger(port) ||
+  port < 1 ||
+  port > 65535 ||
+  args.some(
+    (arg, i) =>
+      arg !== "--preview" &&
+      arg !== "--port" &&
+      !(portIndex >= 0 && i === portIndex + 1),
+  )
+)
+  throw Error(
+    "Usage: bun run dev [--port 5173] / bun run preview [--port 5173]",
+  );
+if (production && !(await Bun.file("dist/package/entry.js").exists()))
+  throw Error("No production build. Run bun run build first.");
+const manifestPath = production ? "dist/package/theme.json" : "theme.json";
+try {
+  if (!(await Bun.file("dev/config.json").exists())) {
+    const manifest = await readManifest(manifestPath);
+    await mkdir("dev", { recursive: true });
+    await writeFile(
+      "dev/config.json",
+      JSON.stringify(
+        initialValue(manifest.configSchema ?? { type: "object" }) ?? {},
+        null,
+        2,
+      ) + "\n",
+      { flag: "wx" },
+    );
+  }
+} catch (error) {
+  if ((error as NodeJS.ErrnoException).code !== "EEXIST")
+    console.error(String(error));
+}
+const virtual = "virtual:picloom-preview",
+  resolved = "\0" + virtual;
+const plugin: Plugin = {
+  name: "picloom-preview",
+  resolveId(id) {
+    if (id === virtual) return resolved;
+  },
+  async load(id) {
+    if (id !== resolved) return;
+    const manifest = await readManifest(manifestPath);
+    const config = JSON.parse(await readFile("dev/config.json", "utf8"));
+    if (!config || Array.isArray(config) || typeof config !== "object")
+      throw Error("dev/config.json must contain an object");
+    return `export const manifest=${JSON.stringify(manifest)};export const config=${JSON.stringify(config)};export const production=${production};`;
+  },
+  configureServer(server) {
+    server.watcher.add([manifestPath, "dev/config.json"]);
+    server.watcher.on("all", (_event, path) => {
+      if (
+        [manifestPath, "dev/config.json"].some(
+          (name) => resolve(path) === resolve(name),
+        )
+      ) {
+        const module = server.moduleGraph.getModuleById(resolved);
+        if (module) server.moduleGraph.invalidateModule(module);
+        server.ws.send({ type: "full-reload" });
+      }
+    });
+    server.middlewares.use(async (req, res, next) => {
+      try {
+        const path = decodeURIComponent(req.url?.split("?")[0] ?? "");
+        // Built resources are served verbatim, including encoded names and ?import.
+        if (production && assetPath(path.slice(1))) {
+          const file = Bun.file(resolve("dist/package", path.slice(1)));
+          if (await file.exists()) {
+            res.setHeader("Content-Type", file.type);
+            res.setHeader("Cache-Control", "no-cache");
+            res.end(new Uint8Array(await file.arrayBuffer()));
+            return;
+          }
+        }
+        if (path !== "/" && path !== "/login") return next();
+        const html = await server.transformIndexHtml(
+          req.url!,
+          await readFile("dev/index.html", "utf8"),
+        );
+        res.setHeader("Content-Type", "text/html; charset=utf-8");
+        res.end(html);
+      } catch (error) {
+        next(error);
+      }
+    });
+  },
+};
+const server = await createServer({
+  configFile: false,
+  appType: "mpa",
+  plugins: [plugin, vue(), tailwindcss()],
+  publicDir: production ? false : "public",
+  server: {
+    host: "127.0.0.1",
+    port,
+    strictPort: true,
+    // Bun's native filesystem watcher can miss repeated replace/write events.
+    watch: { usePolling: true, interval: 150 },
+  },
+});
+await server.listen();
+console.log(
+  `${production ? "Production build" : "Source HMR"} · SIMULATED uploads and login / 模拟上传与登录`,
+);
+server.printUrls();
+let closing = false;
+async function close() {
+  if (closing) return;
+  closing = true;
+  await server.close();
+  process.exit(0);
+}
+process.on("SIGINT", close);
+process.on("SIGTERM", close);