@picloom/create-theme 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lllei
+
+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,34 @@
-# Temporary Holding Version
+# @picloom/create-theme
 
-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.
+Create a standalone Vue 3 Picloom theme with Bun 1.4.3+, simulated preview,
+component/style HMR and ZIP packaging. No application checkout, Node/npm CLI or
+system `zip` is required.
+
+Create a project:
+
+```sh
+bun create @picloom/theme@0.1.0 ./my-theme
+cd my-theme
+bun install
+bun run dev
+bun run build
+bun run preview
+```
+
+The target must not exist; its parent must exist. The creator copies files only;
+it does not install dependencies, initialize Git or publish. Both home and login
+pages start from the same source used by Picloom's built-in default theme.
+`--help` prints usage.
+
+To test local packages, use the `.tgz` workflow in
+[theme tooling](https://llleixx.github.io/picloom/development/theme-tooling.html).
+Maintainers run `bun run build:create-theme` before `bun pm pack --ignore-scripts`.
+The build copies `themes/default/` into the distribution template and bundles
+shared pure helpers into private preview tooling. Do not edit `dist/template/`.
+
+## 中文
+
+基于宿主同一份默认主题源码创建独立 Vue 3 主题。提供模拟预览、热更新、生产产物预览与 ZIP 打包。
+创建工具只复制文件，不覆盖已有目录、不安装依赖、不初始化 Git、不发布。
+模拟预览不连接真实服务；上传、登录与权限必须在隔离测试实例安装后验证。
+通过 npm 创建项目，也可按文档使用本地 `.tgz` 验证开发版本。模板在创建工具构建时自动生成，不手工维护第二份默认主题。

package/dist/template/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lllei
+
+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/dist/template/README.md

@@ -0,0 +1,57 @@
+# Picloom theme / 主题开发
+
+Requires Bun 1.4.3+. This project starts from Picloom's built-in default theme,
+uses only the public Theme SDK, and bundles its own Vue runtime.
+
+```sh
+bun install
+bun run dev
+bun run typecheck
+bun run build
+bun run preview
+```
+
+`dev` listens on http://127.0.0.1:5173; use `bun run dev --port 5174` if occupied.
+The collapsible preview panel switches pages, languages, appearance, identity and
+simulated states. Uploads and login are **simulations**, never real API calls.
+Do not use preview success as evidence that a storage service or authentication works.
+
+Edit `src/Page.vue`, `src/style.css` and `theme.json`. All pages use `src/entry.ts`
+(`entry.js` in the package). Put static package resources in `public/assets/` and
+resolve them with `context.asset("assets/...")`. Imported image/CSS resources are
+also processed by Vite. Keep `style.css` in the manifest's global `styles`: it
+contains all CSS imported by the source entry. Additional page-only styles belong
+in `public/assets/` and the corresponding page's `styles`; preview loads and
+unloads them when changing pages. Arbitrary files outside these inputs are not packaged.
+
+Vue components and CSS support HMR. Entry changes reload the preview. Manifest
+and `dev/config.json` changes reload and remount the theme. Invalid JSON shows a
+development error and is never overwritten. The first preview initializes a
+missing config from schema defaults; later edits never restore removed values.
+There is initially no custom config schema, so the generated config is `{}`.
+
+`preview` loads the existing `dist/package/` JavaScript and styles through the
+same simulated host, without theme source HMR. Build first; source edits are not
+visible until you rebuild. The preview toolbar itself is still a local tool.
+
+The distributable is `dist/<theme-id>-<version>.zip`. Upload it to Picloom's Themes
+page, confirm trust, preview and apply. Test real uploads, login and permissions
+there. Increase `theme.json.version` before distributing changed content; package
+versions are immutable on the host. The package builder checks structure and
+resources; full configuration/manifest validation still runs on installation.
+
+The SDK dependency is pinned to a published npm version.
+Commit your generated `bun.lock` to your own repository after installation.
+
+## 中文
+
+- 使用 Bun 1.4.3+，无需 Node/npm CLI、主仓库或系统 `zip`。
+- `bun run dev` 提供模拟首页、登录页、上传状态、语言和明暗模式；只用于界面开发。
+- 修改 Vue 组件及样式会热更新；入口、清单和本地配置修改后刷新预览。
+- 首次启动时按 Schema 默认值创建 `dev/config.json`，之后清空或删除值不会自动补回。
+- `bun run build` 先检查类型，再构建并生成可安装 ZIP；`bun run preview` 检查已有构建产物。
+- 修改主题 ID、显示名称和版本均以 `theme.json` 为准，静态资源放入 `public/assets/`。
+- 入口导入的样式合并为 `style.css`，须保留清单全局样式声明；页面专属样式通过各页面的 `styles` 引用，切页时分别加载和卸载。
+- 主题包不包含开发面板、本地配置、凭据或源码映射。所有主题配置可能公开，不要保存密钥。
+- 在隔离 Picloom 测试实例安装 ZIP 后验证真实上传和登录；模拟成功不代表真实服务已验证。
+- SDK 依赖固定到 npm 版本；首次安装后将生成的 `bun.lock` 提交到自己的仓库。

package/dist/template/dev/context.ts

@@ -0,0 +1,363 @@
+import type {
+  Config,
+  Manifest,
+  Page,
+  Snapshot,
+  ThemeContext,
+  Upload,
+} from "@picloom/theme-sdk";
+import { languages, messageText } from "./helpers.js";
+export const scenarios = [
+  "ready",
+  "loading",
+  "uploading",
+  "success",
+  "failed",
+  "no-profiles",
+  "login-error",
+] as const;
+export type Scenario = (typeof scenarios)[number];
+const copy = <T>(value: T): T => structuredClone(value);
+export function createPreview(
+  manifest: Manifest,
+  config: Config,
+  navigate: (page: Page) => void,
+) {
+  const listeners = new Set<(snapshot: Snapshot) => void>();
+  const timers = new Set<ReturnType<typeof setTimeout>>();
+  const motion = matchMedia("(prefers-color-scheme: dark)");
+  const state: Snapshot = {
+    page: location.pathname === "/login" ? "login" : "home",
+    site: {
+      name: "Preview gallery",
+      homeTitle: "Preview gallery",
+      description: "SIMULATED uploads and login · 模拟上传与登录",
+      logoUrl: "",
+      faviconUrl: "",
+    },
+    user: null,
+    locale: manifest.defaultLocale,
+    locales: manifest.supportedLocales,
+    languages: languages.filter((language) =>
+      manifest.supportedLocales.includes(language.tag),
+    ),
+    defaultLocale: manifest.defaultLocale,
+    mode: "auto",
+    dark: motion.matches,
+    profiles: [
+      {
+        id: "mock",
+        name: "Simulated / 模拟上传",
+        enabled: true,
+        available: true,
+        maxUploadBytes: 50 * 1024 ** 2,
+        allowedMimeTypes: [
+          "image/jpeg",
+          "image/png",
+          "image/webp",
+          "image/svg+xml",
+        ],
+        reason: null,
+      },
+    ],
+    selectedProfileId: "mock",
+    uploads: [],
+    loading: false,
+    error: "",
+    login: { busy: false, error: "", expired: false, unavailable: false },
+    copy: {
+      format: "URL",
+      auto: false,
+      formats: ["URL", "Markdown", "HTML", "BBCode"],
+    },
+    notice: "",
+  };
+  let scenario: Scenario = "ready",
+    alive = true;
+  const text = (en: string, zh: string) => (state.locale === "zh-CN" ? zh : en);
+  function emit() {
+    if (alive) for (const listener of listeners) listener(copy(state));
+  }
+  function later(callback: () => void, delay: number) {
+    const timer = setTimeout(() => {
+      timers.delete(timer);
+      if (alive) callback();
+    }, delay);
+    timers.add(timer);
+  }
+  function clear() {
+    for (const timer of timers) clearTimeout(timer);
+    timers.clear();
+  }
+  function notify(en: string, zh: string) {
+    state.notice = text(en, zh);
+    emit();
+  }
+  function result(id: string) {
+    return { id, url: `https://example.invalid/simulated/${id}.png` };
+  }
+  function format(url: string) {
+    switch (state.copy.format) {
+      case "Markdown":
+        return `![](${url})`;
+      case "HTML":
+        return `<img src="${url}" alt="">`;
+      case "BBCode":
+        return `[img]${url}[/img]`;
+      default:
+        return url;
+    }
+  }
+  async function copyText(value: string) {
+    try {
+      await navigator.clipboard.writeText(value);
+      notify("Copied", "已复制");
+    } catch {
+      notify("Clipboard unavailable", "剪贴板不可用");
+    }
+  }
+  function run(item: Upload) {
+    later(() => {
+      if (
+        !state.uploads.includes(item) ||
+        !["queued", "uploading"].includes(item.status)
+      )
+        return;
+      item.status = "uploading";
+      item.progress = Math.min(100, item.progress + 25);
+      if (item.progress === 100) {
+        item.status = "success";
+        item.result = result(item.id);
+        if (state.copy.auto) void copyText(format(item.result.url));
+      } else run(item);
+      emit();
+    }, 400);
+  }
+  function add(name: string, size: number, sourceUrl?: string) {
+    if (
+      !state.profiles.some(
+        (profile) =>
+          profile.id === state.selectedProfileId && profile.available,
+      )
+    ) {
+      notify(
+        "Choose an available simulated profile",
+        "请选择可用的模拟上传方案",
+      );
+      return;
+    }
+    const item: Upload = {
+      id: crypto.randomUUID(),
+      name,
+      size,
+      profileName: state.profiles[0]!.name,
+      sourceUrl,
+      status: "queued",
+      progress: 0,
+    };
+    state.uploads = [...state.uploads, item];
+    run(item);
+    emit();
+  }
+  function setScenario(value: Scenario) {
+    clear();
+    scenario = value;
+    state.uploads = [];
+    state.loading = value === "loading";
+    state.login.busy = false;
+    state.login.error =
+      value === "login-error"
+        ? text("Simulated login failure", "模拟登录失败")
+        : "";
+    state.notice = "";
+    state.profiles = state.profiles.map((profile) => ({
+      ...profile,
+      available: value !== "no-profiles",
+    }));
+    state.selectedProfileId = value === "no-profiles" ? "" : "mock";
+    if (["uploading", "success", "failed"].includes(value)) {
+      const item: Upload = {
+        id: "preview-image",
+        name: "simulated-image.png",
+        size: 128 * 1024,
+        profileName: state.profiles[0]!.name,
+        status: value as Upload["status"],
+        progress: value === "uploading" ? 50 : value === "success" ? 100 : 0,
+      };
+      if (value === "success") item.result = result(item.id);
+      if (value === "failed") {
+        item.error = text("Simulated upload failure", "模拟上传失败");
+        item.resumable = true;
+      }
+      state.uploads = [item];
+    }
+    emit();
+  }
+  function appearance() {
+    state.dark = state.mode === "auto" ? motion.matches : state.mode === "dark";
+    document.documentElement.classList.toggle("dark", state.dark);
+    emit();
+  }
+  motion.addEventListener("change", appearance);
+  const ctx: ThemeContext = {
+    apiVersion: 1,
+    config: copy(config),
+    getSnapshot: () => copy(state),
+    subscribe(listener) {
+      listeners.add(listener);
+      listener(copy(state));
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    asset(path) {
+      if (
+        !path ||
+        path.startsWith("/") ||
+        /[\\:?*<>"|]/.test(path) ||
+        path.split("/").some((part) => !part || part === "." || part === "..")
+      )
+        throw Error("Invalid package asset path");
+      return new URL("/" + path, location.origin).href;
+    },
+    t(key, params = {}) {
+      return messageText(manifest, state.locale, key).replace(
+        /\{(\w+)\}/g,
+        (match, name: string) => String(params[name] ?? match),
+      );
+    },
+    localized(value) {
+      if (typeof value === "string") return value;
+      if (!value || typeof value !== "object" || Array.isArray(value))
+        return "";
+      return typeof value[state.locale] === "string"
+        ? (value[state.locale] as string)
+        : "";
+    },
+    setLocale(language) {
+      if (!state.locales.includes(language))
+        throw Error("Language is not supported");
+      state.locale = language;
+      document.documentElement.lang = language;
+      if (state.login.error)
+        state.login.error = text("Simulated login failure", "模拟登录失败");
+      for (const item of state.uploads)
+        if (item.error)
+          item.error = text("Simulated upload failure", "模拟上传失败");
+      emit();
+    },
+    setMode(mode) {
+      state.mode = mode;
+      appearance();
+    },
+    navigate(page) {
+      if (page === "app")
+        notify(
+          "Workspace is unavailable in simulated preview",
+          "模拟预览不提供管理后台",
+        );
+      else navigate(page);
+    },
+    selectProfile(id) {
+      state.selectedProfileId = id;
+      emit();
+    },
+    async refresh() {
+      state.error = "";
+      setScenario("ready");
+    },
+    uploads: {
+      add(files) {
+        for (const file of files) add(file.name, file.size);
+      },
+      addUrls(urls) {
+        for (const sourceUrl of urls) {
+          try {
+            const url = new URL(sourceUrl);
+            if (!["http:", "https:"].includes(url.protocol)) throw Error();
+            add(
+              url.pathname.split("/").pop() || "remote-image",
+              1024,
+              sourceUrl,
+            );
+          } catch {
+            notify("Invalid image URL", "图片地址无效");
+          }
+        }
+      },
+      async cancel(id) {
+        const item = state.uploads.find((item) => item.id === id);
+        if (item && ["queued", "uploading"].includes(item.status))
+          item.status = "cancelled";
+        emit();
+      },
+      resume(id) {
+        const item = state.uploads.find((item) => item.id === id);
+        if (item?.resumable) {
+          item.status = "queued";
+          item.error = undefined;
+          run(item);
+          emit();
+        }
+      },
+      async dismiss(id) {
+        state.uploads = state.uploads.filter((item) => item.id !== id);
+        emit();
+      },
+    },
+    links: {
+      format,
+      async copy(url) {
+        await copyText(format(url));
+      },
+      async copyAll() {
+        await copyText(
+          state.uploads
+            .flatMap((item) => (item.result ? [format(item.result.url)] : []))
+            .join("\n"),
+        );
+      },
+      setPreferences(format, auto) {
+        if (!state.copy.formats.includes(format))
+          throw Error("Unknown copy format");
+        state.copy = { ...state.copy, format, auto };
+        emit();
+      },
+    },
+    async login(username, _password) {
+      state.login.busy = true;
+      state.login.error = "";
+      emit();
+      await new Promise<void>((resolve) => setTimeout(resolve, 150));
+      if (!alive) return;
+      state.login.busy = false;
+      if (scenario === "login-error")
+        state.login.error = text("Simulated login failure", "模拟登录失败");
+      else {
+        state.user = { name: username || "Preview user" };
+        navigate("home");
+      }
+      emit();
+    },
+  };
+  appearance();
+  document.documentElement.lang = state.locale;
+  return {
+    ctx,
+    setScenario,
+    setPage(page: Page) {
+      state.page = page;
+      emit();
+    },
+    setUser(signedIn: boolean) {
+      state.user = signedIn ? { name: "Preview user" } : null;
+      emit();
+    },
+    dispose() {
+      alive = false;
+      clear();
+      listeners.clear();
+      motion.removeEventListener("change", appearance);
+    },
+  };
+}

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

@@ -0,0 +1,6 @@
+/// <reference types="vite/client" />
+declare module "*.vue" {
+  import type { DefineComponent } from "vue";
+  const component: DefineComponent;
+  export default component;
+}

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

@@ -0,0 +1,18 @@
+import type { Field, Json } from "@picloom/theme-sdk";
+export function initialValue(schema: Field, value?: Json): Json | undefined;
+export function messageText(
+  catalog: {
+    defaultLocale: string;
+    messages: Record<string, Record<string, string>>;
+  },
+  locale: string,
+  key: string,
+): string;
+export const supportedLocales: readonly string[];
+export const languages: readonly {
+  tag: string;
+  name: string;
+  direction: string;
+}[];
+export function safeName(value: unknown): value is string;
+export function assetPath(value: unknown): value is string;

package/dist/template/dev/helpers.js

@@ -0,0 +1,114 @@
+// ../../shared/field-schema.ts
+function cloneJson(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+function pointer(key) {
+  return key.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+function sensitivePaths(schema, path = "") {
+  if (schema["x-sensitive"] === true || schema.type === "array" && schema.items && sensitivePaths(schema.items).length > 0)
+    return [path];
+  return Object.entries(schema.properties ?? {}).flatMap(([key, rule]) => sensitivePaths(rule, path + "/" + pointer(key)));
+}
+var keywords = new Set([
+  "$schema",
+  "type",
+  "properties",
+  "required",
+  "additionalProperties",
+  "items",
+  "enum",
+  "const",
+  "default",
+  "minimum",
+  "maximum",
+  "exclusiveMinimum",
+  "exclusiveMaximum",
+  "multipleOf",
+  "minLength",
+  "maxLength",
+  "pattern",
+  "format",
+  "minItems",
+  "maxItems",
+  "uniqueItems",
+  "if",
+  "then",
+  "else",
+  "allOf",
+  "anyOf",
+  "oneOf",
+  "not",
+  "x-localized",
+  "x-sensitive",
+  "x-immutable",
+  "x-ui"
+]);
+function initialValue(schema, value) {
+  if (schema["x-sensitive"] === true || schema.type === "array" && sensitivePaths(schema).length)
+    return;
+  const seed = value === undefined ? schema.default : value;
+  if (schema.type === "object") {
+    if (seed !== undefined && (!seed || typeof seed !== "object" || Array.isArray(seed)))
+      return cloneJson(seed);
+    const result = seed === undefined ? {} : cloneJson(seed);
+    for (const [key, rule] of Object.entries(schema.properties ?? {})) {
+      const child = initialValue(rule, Object.hasOwn(result, key) ? result[key] : undefined);
+      if (child !== undefined)
+        result[key] = child;
+      else
+        delete result[key];
+    }
+    return seed !== undefined || Object.keys(result).length ? result : undefined;
+  }
+  if (schema.type === "array" && Array.isArray(seed))
+    return seed.map((item) => initialValue(schema.items, item) ?? null);
+  return seed === undefined ? undefined : cloneJson(seed);
+}
+// ../../shared/package-localization.ts
+function localeCandidates(locale, fallback) {
+  const tag = Intl.getCanonicalLocales(locale)[0];
+  return [
+    ...new Set([
+      tag,
+      tag.split("-")[0],
+      Intl.getCanonicalLocales(fallback)[0]
+    ])
+  ];
+}
+function messageText(resource, locale, key) {
+  for (const tag of localeCandidates(locale, resource.defaultLocale)) {
+    const dictionary = resource.messages[tag];
+    const value = dictionary && Object.hasOwn(dictionary, key) ? dictionary[key] : undefined;
+    if (value !== undefined)
+      return value;
+  }
+  return key;
+}
+// ../../shared/locales.ts
+var languages = [
+  {
+    tag: "zh-CN",
+    name: "简体中文",
+    direction: "ltr",
+    aliases: ["zh"]
+  },
+  {
+    tag: "en-US",
+    name: "English",
+    direction: "ltr",
+    aliases: ["en"]
+  }
+];
+var supportedLocales = languages.map((language) => language.tag);
+// ../../shared/theme-package.ts
+var safeName = (v) => typeof v === "string" && /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,99}$/.test(v) && !v.endsWith(".");
+var assetPath = (v) => typeof v === "string" && v.length <= 240 && !/[\\:< >"|?*\x00-\x1f]/.test(v) && v.split("/").every((p) => !!p && p !== "." && p !== ".." && !/[. ]$/.test(p));
+export {
+  assetPath,
+  initialValue,
+  languages,
+  messageText,
+  safeName,
+  supportedLocales
+};

package/dist/template/dev/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Picloom theme preview</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/dev/main.ts"></script>
+  </body>
+</html>