wallpaper-engine 1.0.0

package/dist/plugin/index.d.ts

@@ -0,0 +1,334 @@
+import { Plugin } from 'vite';
+
+/**
+ * Runtime value of a color property.
+ * `value` is `"R G B"` where each channel is in the **0–1** range.
+ * Multiply by 255 to convert for CSS `rgb()`.
+ *
+ * @example
+ * const [r, g, b] = props.myColor.value.split(' ').map(c => Math.ceil(+c * 255));
+ * el.style.color = `rgb(${r},${g},${b})`;
+ */
+interface WallpaperColorValue {
+    /** Color string `"R G B"` — each channel 0.0–1.0. */
+    value: string;
+}
+/** Runtime value of a slider property. */
+interface WallpaperSliderValue {
+    value: number;
+}
+/** Runtime value of a checkbox (`bool`) property. */
+interface WallpaperBoolValue {
+    value: boolean;
+}
+/**
+ * Runtime value of a combo (dropdown) property.
+ * `value` is the hidden key configured in the editor;
+ * `text` is the visible display label.
+ */
+interface WallpaperComboValue {
+    /** The hidden value configured on the combo option. */
+    value: string;
+    /** Display label of the selected option (may be a `ui_` localization token). */
+    text: string;
+}
+/** Runtime value of a text-input property. */
+interface WallpaperTextValue {
+    value: string;
+}
+/**
+ * Runtime value of a file property.
+ * Prepend `"file:///"` to `value` before using it as a URL.
+ *
+ * @example
+ * img.src = 'file:///' + props.myImage.value;
+ */
+interface WallpaperFileValue {
+    /** File path — prepend `"file:///"` before use as a URL. */
+    value: string;
+}
+/**
+ * Runtime value of a directory property in `ondemand` mode.
+ * An empty string means no directory is currently selected.
+ * Call `wallpaperRequestRandomFileForProperty` to retrieve a random file.
+ */
+interface WallpaperDirectoryValue {
+    /** Directory path, or empty string when no directory is selected. */
+    value: string;
+}
+
+/** File type accepted by file/directory properties */
+type WallpaperFileType = "image" | "video";
+/**
+ * Localization map inside `project.json`'s `general.localization`.
+ * Outer key: BCP-47 language code (e.g. `"en-us"`, `"de-de"`, `"zh-chs"`).
+ * Inner key: `ui_` token string. Value: translated display text.
+ *
+ * @example
+ * {
+ *   "en-us": { "ui_mycolor": "Background color" },
+ *   "de-de": { "ui_mycolor": "Hintergrundfarbe" }
+ * }
+ */
+type WallpaperLocalization = Record<string, Record<string, string>>;
+interface WallpaperPropertyBase {
+    /** Display label shown in the properties panel, or a `ui_` token for localization */
+    text: string;
+    /** Sort index within the properties panel */
+    order?: number;
+    /** Internal sequential index (auto-assigned by the editor) */
+    index?: number;
+    /**
+     * JavaScript expression evaluated to determine visibility.
+     * References other property keys, e.g. `"showclock.value == true"`.
+     */
+    condition?: string;
+}
+/**
+ * Color picker property. Shows a color picker to the user.
+ * The runtime value is `"R G B"` where each channel is in the **0–1** range.
+ */
+interface WallpaperColorProperty extends WallpaperPropertyBase {
+    type: "color";
+    /** Default color as `"R G B"` with each channel in the 0–1 range. */
+    value: string;
+}
+/**
+ * Slider property. Lets users pick a number in a defined range.
+ * Enable `fraction` for decimal values; `precision` controls decimal places (default: `2`).
+ */
+interface WallpaperSliderProperty extends WallpaperPropertyBase {
+    type: "slider";
+    /** Default value — should be within `[min, max]`. */
+    value: number;
+    min: number;
+    max: number;
+    /** Allow fractional (decimal) values. */
+    fraction?: boolean;
+    /** Number of decimal places when `fraction` is `true` (default: `2`). */
+    precision?: number;
+}
+/** Checkbox (on/off toggle) property. */
+interface WallpaperBoolProperty extends WallpaperPropertyBase {
+    type: "bool";
+    /** Default checked state. */
+    value: boolean;
+}
+interface WallpaperComboOption {
+    /** Human-readable label shown in the dropdown, or a `ui_` token */
+    label: string;
+    /** Hidden value passed to `applyUserProperties` */
+    value: string;
+}
+interface WallpaperComboProperty extends WallpaperPropertyBase {
+    type: "combo";
+    /** Key of the default selected option */
+    value: string;
+    options: WallpaperComboOption[];
+}
+/** Free-text input property. */
+interface WallpaperTextInputProperty extends WallpaperPropertyBase {
+    type: "textinput";
+    /** Default text value. */
+    value: string;
+}
+/**
+ * File selector property. Lets users import a single image or video file.
+ * The runtime `value` path must be prefixed with `"file:///"` before use as a URL.
+ */
+interface WallpaperFileProperty extends WallpaperPropertyBase {
+    type: "file";
+    /** Default file path (empty string = no file selected). */
+    value: string;
+    fileType?: WallpaperFileType;
+}
+/**
+ * Directory selector for mass-importing image or video files.
+ * Choose between `"ondemand"` (one random file at a time via
+ * `wallpaperRequestRandomFileForProperty`) and `"fetchall"` (all files
+ * surfaced via `userDirectoryFilesAddedOrChanged` / `userDirectoryFilesRemoved`).
+ */
+interface WallpaperDirectoryProperty extends WallpaperPropertyBase {
+    type: "directory";
+    /** Default directory path (empty string = no directory selected). */
+    value: string;
+    fileType?: WallpaperFileType;
+    /**
+     * - `"ondemand"` — call `wallpaperRequestRandomFileForProperty` to get a file.
+     * - `"fetchall"` — all files are surfaced via `userDirectoryFilesAddedOrChanged`.
+     */
+    mode: "ondemand" | "fetchall";
+}
+/** Union of all property definition types stored in `project.json`. */
+type WallpaperPropertyDefinition = WallpaperColorProperty | WallpaperSliderProperty | WallpaperBoolProperty | WallpaperComboProperty | WallpaperTextInputProperty | WallpaperFileProperty | WallpaperDirectoryProperty;
+/** The `general` block inside `project.json`. */
+interface WallpaperProjectGeneral {
+    properties?: Record<string, WallpaperPropertyDefinition>;
+    localization?: WallpaperLocalization;
+}
+/** Full shape of the `project.json` file generated by Wallpaper Engine */
+interface WallpaperProject {
+    /** Entry HTML file name relative to the project directory */
+    file: string;
+    /** Wallpaper title shown in the Wallpaper Engine UI */
+    title: string;
+    type: "web";
+    /**
+     * Set to `true` to enable audio data delivery.
+     * Wallpaper Engine auto-detects this from `wallpaperRegisterAudioListener`
+     * calls, but you can also set it manually.
+     */
+    supportsaudioprocessing?: boolean;
+    general?: WallpaperProjectGeneral;
+}
+
+type Without<T, K extends keyof T> = Omit<T, K>;
+/** Define a color property (value: `"R G B"` in 0–1 range) */
+declare function colorProperty(opts: Without<WallpaperColorProperty, "type">): WallpaperColorProperty;
+/** Define a numeric slider property */
+declare function sliderProperty(opts: Without<WallpaperSliderProperty, "type">): WallpaperSliderProperty;
+/** Define a boolean checkbox property */
+declare function boolProperty(opts: Without<WallpaperBoolProperty, "type">): WallpaperBoolProperty;
+/** Define a dropdown (combo) property */
+declare function comboProperty(opts: Without<WallpaperComboProperty, "type">): WallpaperComboProperty;
+/** Define a text input property */
+declare function textInputProperty(opts: Without<WallpaperTextInputProperty, "type">): WallpaperTextInputProperty;
+/** Define a file picker property */
+declare function fileProperty(opts: Without<WallpaperFileProperty, "type">): WallpaperFileProperty;
+/** Define a directory picker property */
+declare function directoryProperty(opts: Without<WallpaperDirectoryProperty, "type">): WallpaperDirectoryProperty;
+/**
+ * Maps a single property **definition** type to its **runtime value** type.
+ *
+ * Useful for building generic helpers that operate on any property kind.
+ *
+ * @example
+ * type T = PropertyDefinitionToValue<WallpaperColorProperty>;
+ * // → WallpaperColorValue
+ */
+type PropertyDefinitionToValue<T extends WallpaperPropertyDefinition> = T extends {
+    type: "color";
+} ? WallpaperColorValue : T extends {
+    type: "slider";
+} ? WallpaperSliderValue : T extends {
+    type: "bool";
+} ? WallpaperBoolValue : T extends {
+    type: "combo";
+} ? WallpaperComboValue : T extends {
+    type: "textinput";
+} ? WallpaperTextValue : T extends {
+    type: "file";
+} ? WallpaperFileValue : T extends {
+    type: "directory";
+} ? WallpaperDirectoryValue : never;
+/**
+ * Infer the strongly-typed `applyUserProperties` argument from a property
+ * definition record. Define your properties once in a shared file, then pass
+ * `typeof yourProperties` here to get full autocomplete on every property key
+ * and its value type.
+ *
+ * @example
+ * // properties.ts — shared between vite.config.ts and wallpaper source
+ * import { colorProperty, sliderProperty } from 'wallpaper-engine/plugin';
+ *
+ * export const myProperties = {
+ *   bgcolor: colorProperty({ text: 'Background Color', value: '0 0 0' }),
+ *   speed:   sliderProperty({ text: 'Speed', value: 1, min: 0, max: 5 }),
+ * };
+ *
+ * // vite.config.ts
+ * import { wallpaperEnginePlugin } from 'wallpaper-engine/plugin';
+ * import { myProperties } from './properties';
+ *
+ * export default defineConfig({
+ *   plugins: [wallpaperEnginePlugin({ title: 'My Wallpaper', properties: myProperties })],
+ * });
+ *
+ * // wallpaper.ts
+ * import type { WallpaperUserPropertiesOf } from 'wallpaper-engine/plugin';
+ * import type { myProperties } from './properties';
+ *
+ * type MyProps = WallpaperUserPropertiesOf<typeof myProperties>;
+ * // → { bgcolor: WallpaperColorValue; speed: WallpaperSliderValue }
+ *
+ * window.wallpaperPropertyListener = {
+ *   applyUserProperties(props: Partial<MyProps>) {
+ *     if (props.bgcolor) el.style.background = wallpaperColorToRgb(props.bgcolor.value);
+ *     if (props.speed !== undefined) setSpeed(props.speed.value); // number ✓
+ *   },
+ * };
+ */
+type WallpaperUserPropertiesOf<T extends Record<string, WallpaperPropertyDefinition>> = {
+    readonly [K in keyof T]: PropertyDefinitionToValue<T[K]>;
+};
+interface WallpaperEnginePluginOptions {
+    /**
+     * Entry HTML file name relative to the project root.
+     * @default "index.html"
+     */
+    file?: string;
+    /** Wallpaper title shown in the Wallpaper Engine UI */
+    title: string;
+    /**
+     * Enable audio data delivery to `wallpaperRegisterAudioListener`.
+     * Wallpaper Engine can auto-detect this, but you can set it explicitly.
+     * @default false
+     */
+    supportsAudioProcessing?: boolean;
+    /**
+     * User-configurable properties exposed in the Wallpaper Engine properties panel.
+     * Keys become the property identifiers accessed in `applyUserProperties`.
+     *
+     * @example
+     * properties: {
+     *   bgcolor: colorProperty({ text: 'Background Color', value: '0 0 0' }),
+     *   speed:   sliderProperty({ text: 'Speed', value: 1, min: 0, max: 5 }),
+     * }
+     */
+    properties?: Record<string, WallpaperPropertyDefinition>;
+    /**
+     * Localization strings for property labels and combo option labels.
+     * Keys are BCP 47 language codes (e.g. `"en-us"`, `"de-de"`, `"zh-chs"`).
+     * Property labels that should be translated must start with `ui_`.
+     *
+     * @example
+     * localization: {
+     *   'en-us': { 'ui_bgcolor': 'Background Color' },
+     *   'de-de': { 'ui_bgcolor': 'Hintergrundfarbe' },
+     * }
+     */
+    localization?: WallpaperLocalization;
+    /**
+     * Enable the in-browser dev overlay during `vite dev`. The overlay stubs
+     * every `window.wallpaper*` global, renders a draggable panel to edit each
+     * property in real time, and lets you fire audio/media/plugin events
+     * manually — so wallpapers can be developed without round-tripping through
+     * the Wallpaper Engine host application.
+     *
+     * Disabled automatically for production builds regardless of this setting.
+     *
+     * @default true
+     */
+    devtools?: boolean;
+}
+/**
+ * Vite plugin that auto-generates `project.json` into the build output.
+ *
+ * @example
+ * // vite.config.ts
+ * import { wallpaperEnginePlugin, colorProperty } from 'wallpaper-engine/plugin';
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     wallpaperEnginePlugin({
+ *       title: 'My Wallpaper',
+ *       properties: {
+ *         bgcolor: colorProperty({ text: 'Background Color', value: '0 0 0' }),
+ *       },
+ *     }),
+ *   ],
+ * });
+ */
+declare function wallpaperEnginePlugin(options: WallpaperEnginePluginOptions): Plugin;
+
+export { type PropertyDefinitionToValue, type WallpaperBoolProperty, type WallpaperColorProperty, type WallpaperComboOption, type WallpaperComboProperty, type WallpaperDirectoryProperty, type WallpaperEnginePluginOptions, type WallpaperFileProperty, type WallpaperFileType, type WallpaperLocalization, type WallpaperProject, type WallpaperProjectGeneral, type WallpaperPropertyDefinition, type WallpaperSliderProperty, type WallpaperTextInputProperty, type WallpaperUserPropertiesOf, boolProperty, colorProperty, comboProperty, directoryProperty, fileProperty, sliderProperty, textInputProperty, wallpaperEnginePlugin };

package/dist/plugin/index.js

@@ -0,0 +1,132 @@
+// src/plugin/index.ts
+function colorProperty(opts) {
+  return { type: "color", ...opts };
+}
+function sliderProperty(opts) {
+  return { type: "slider", ...opts };
+}
+function boolProperty(opts) {
+  return { type: "bool", ...opts };
+}
+function comboProperty(opts) {
+  return { type: "combo", ...opts };
+}
+function textInputProperty(opts) {
+  return { type: "textinput", ...opts };
+}
+function fileProperty(opts) {
+  return { type: "file", ...opts };
+}
+function directoryProperty(opts) {
+  return { type: "directory", ...opts };
+}
+function wallpaperEnginePlugin(options) {
+  const devtoolsEnabled = options.devtools !== false;
+  const VIRTUAL_ID = "virtual:wallpaper-engine/devtools";
+  const RESOLVED_ID = "\0" + VIRTUAL_ID;
+  let isServe = false;
+  let cachedClientCode;
+  const loadClientCode = async () => {
+    if (cachedClientCode !== void 0) return cachedClientCode;
+    const { readFileSync } = await import("fs");
+    const { fileURLToPath } = await import("url");
+    const url = new URL("./devtools/client.js", import.meta.url);
+    cachedClientCode = readFileSync(fileURLToPath(url), "utf8");
+    return cachedClientCode;
+  };
+  return {
+    name: "wallpaper-engine",
+    configResolved(config) {
+      isServe = config.command === "serve";
+    },
+    configureServer(server) {
+      if (!devtoolsEnabled) return;
+      void Promise.all([import("fs"), import("url")]).then(
+        ([fs, { fileURLToPath }]) => {
+          const clientPath = fileURLToPath(
+            new URL("./devtools/client.js", import.meta.url)
+          );
+          fs.watchFile(clientPath, { interval: 500 }, () => {
+            cachedClientCode = void 0;
+            const mod = server.moduleGraph.getModuleById(RESOLVED_ID);
+            if (mod) server.moduleGraph.invalidateModule(mod);
+            server.ws.send({ type: "full-reload" });
+          });
+          server.httpServer?.once("close", () => {
+            fs.unwatchFile(clientPath);
+          });
+        }
+      );
+    },
+    resolveId(id) {
+      if (id === VIRTUAL_ID) return RESOLVED_ID;
+      return null;
+    },
+    async load(id) {
+      if (id !== RESOLVED_ID) return null;
+      const properties = options.properties ? assignIndices(options.properties) : {};
+      const cfg = {
+        title: options.title,
+        properties,
+        localization: options.localization ?? {}
+      };
+      return "window.__WE_DEVTOOLS_CONFIG__ = " + JSON.stringify(cfg) + ";\n" + await loadClientCode();
+    },
+    transformIndexHtml() {
+      if (!isServe || !devtoolsEnabled) return;
+      return [
+        {
+          tag: "script",
+          attrs: { type: "module", src: "/@id/" + VIRTUAL_ID },
+          injectTo: "head-prepend"
+        }
+      ];
+    },
+    generateBundle() {
+      const properties = options.properties ? assignIndices(options.properties) : void 0;
+      const general = {};
+      if (properties) general.properties = properties;
+      if (options.localization) general.localization = options.localization;
+      const project = {
+        file: options.file ?? "index.html",
+        title: options.title,
+        type: "web"
+      };
+      if (options.supportsAudioProcessing) {
+        project.supportsaudioprocessing = true;
+      }
+      if (Object.keys(general).length > 0) {
+        project.general = general;
+      }
+      this.emitFile({
+        type: "asset",
+        fileName: "project.json",
+        source: JSON.stringify(project, null, "	")
+      });
+    }
+  };
+}
+function assignIndices(properties) {
+  const result = {};
+  let i = 0;
+  for (const [key, prop] of Object.entries(properties)) {
+    result[key] = {
+      index: i,
+      order: i,
+      ...prop
+    };
+    i++;
+  }
+  return result;
+}
+export {
+  boolProperty,
+  colorProperty,
+  comboProperty,
+  directoryProperty,
+  fileProperty,
+  sliderProperty,
+  textInputProperty,
+  wallpaperEnginePlugin
+};
+//# sourceMappingURL=index.js.map

package/dist/plugin/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/plugin/index.ts"],"sourcesContent":["import type { Plugin } from \"vite\";\r\nimport type {\r\n  WallpaperBoolValue,\r\n  WallpaperColorValue,\r\n  WallpaperComboValue,\r\n  WallpaperDirectoryValue,\r\n  WallpaperFileValue,\r\n  WallpaperSliderValue,\r\n  WallpaperTextValue,\r\n} from \"../types/listeners\";\r\nimport type {\r\n  WallpaperBoolProperty,\r\n  WallpaperColorProperty,\r\n  WallpaperComboProperty,\r\n  WallpaperDirectoryProperty,\r\n  WallpaperFileProperty,\r\n  WallpaperLocalization,\r\n  WallpaperProject,\r\n  WallpaperProjectGeneral,\r\n  WallpaperPropertyDefinition,\r\n  WallpaperSliderProperty,\r\n  WallpaperTextInputProperty,\r\n} from \"../types/project\";\r\n\r\nexport type {\r\n  WallpaperBoolProperty,\r\n  WallpaperColorProperty,\r\n  WallpaperComboProperty,\r\n  WallpaperDirectoryProperty,\r\n  WallpaperFileProperty,\r\n  WallpaperLocalization,\r\n  WallpaperProject,\r\n  WallpaperProjectGeneral,\r\n  WallpaperPropertyDefinition,\r\n  WallpaperSliderProperty,\r\n  WallpaperTextInputProperty,\r\n};\r\nexport type { WallpaperComboOption, WallpaperFileType } from \"../types/project\";\r\n\r\n// ---------------------------------------------------------------------------\r\n// Property builder helpers\r\n// ---------------------------------------------------------------------------\r\n\r\ntype Without<T, K extends keyof T> = Omit<T, K>;\r\n\r\n/** Define a color property (value: `\"R G B\"` in 0–1 range) */\r\nexport function colorProperty(\r\n  opts: Without<WallpaperColorProperty, \"type\">,\r\n): WallpaperColorProperty {\r\n  return { type: \"color\", ...opts };\r\n}\r\n\r\n/** Define a numeric slider property */\r\nexport function sliderProperty(\r\n  opts: Without<WallpaperSliderProperty, \"type\">,\r\n): WallpaperSliderProperty {\r\n  return { type: \"slider\", ...opts };\r\n}\r\n\r\n/** Define a boolean checkbox property */\r\nexport function boolProperty(\r\n  opts: Without<WallpaperBoolProperty, \"type\">,\r\n): WallpaperBoolProperty {\r\n  return { type: \"bool\", ...opts };\r\n}\r\n\r\n/** Define a dropdown (combo) property */\r\nexport function comboProperty(\r\n  opts: Without<WallpaperComboProperty, \"type\">,\r\n): WallpaperComboProperty {\r\n  return { type: \"combo\", ...opts };\r\n}\r\n\r\n/** Define a text input property */\r\nexport function textInputProperty(\r\n  opts: Without<WallpaperTextInputProperty, \"type\">,\r\n): WallpaperTextInputProperty {\r\n  return { type: \"textinput\", ...opts };\r\n}\r\n\r\n/** Define a file picker property */\r\nexport function fileProperty(\r\n  opts: Without<WallpaperFileProperty, \"type\">,\r\n): WallpaperFileProperty {\r\n  return { type: \"file\", ...opts };\r\n}\r\n\r\n/** Define a directory picker property */\r\nexport function directoryProperty(\r\n  opts: Without<WallpaperDirectoryProperty, \"type\">,\r\n): WallpaperDirectoryProperty {\r\n  return { type: \"directory\", ...opts };\r\n}\r\n\r\n// ---------------------------------------------------------------------------\r\n// Property definition → runtime value type mapping\r\n// ---------------------------------------------------------------------------\r\n\r\n/**\r\n * Maps a single property **definition** type to its **runtime value** type.\r\n *\r\n * Useful for building generic helpers that operate on any property kind.\r\n *\r\n * @example\r\n * type T = PropertyDefinitionToValue<WallpaperColorProperty>;\r\n * // → WallpaperColorValue\r\n */\r\nexport type PropertyDefinitionToValue<T extends WallpaperPropertyDefinition> =\r\n  T extends { type: \"color\" }\r\n    ? WallpaperColorValue\r\n    : T extends { type: \"slider\" }\r\n      ? WallpaperSliderValue\r\n      : T extends { type: \"bool\" }\r\n        ? WallpaperBoolValue\r\n        : T extends { type: \"combo\" }\r\n          ? WallpaperComboValue\r\n          : T extends { type: \"textinput\" }\r\n            ? WallpaperTextValue\r\n            : T extends { type: \"file\" }\r\n              ? WallpaperFileValue\r\n              : T extends { type: \"directory\" }\r\n                ? WallpaperDirectoryValue\r\n                : never;\r\n\r\n/**\r\n * Infer the strongly-typed `applyUserProperties` argument from a property\r\n * definition record. Define your properties once in a shared file, then pass\r\n * `typeof yourProperties` here to get full autocomplete on every property key\r\n * and its value type.\r\n *\r\n * @example\r\n * // properties.ts — shared between vite.config.ts and wallpaper source\r\n * import { colorProperty, sliderProperty } from 'wallpaper-engine/plugin';\r\n *\r\n * export const myProperties = {\r\n *   bgcolor: colorProperty({ text: 'Background Color', value: '0 0 0' }),\r\n *   speed:   sliderProperty({ text: 'Speed', value: 1, min: 0, max: 5 }),\r\n * };\r\n *\r\n * // vite.config.ts\r\n * import { wallpaperEnginePlugin } from 'wallpaper-engine/plugin';\r\n * import { myProperties } from './properties';\r\n *\r\n * export default defineConfig({\r\n *   plugins: [wallpaperEnginePlugin({ title: 'My Wallpaper', properties: myProperties })],\r\n * });\r\n *\r\n * // wallpaper.ts\r\n * import type { WallpaperUserPropertiesOf } from 'wallpaper-engine/plugin';\r\n * import type { myProperties } from './properties';\r\n *\r\n * type MyProps = WallpaperUserPropertiesOf<typeof myProperties>;\r\n * // → { bgcolor: WallpaperColorValue; speed: WallpaperSliderValue }\r\n *\r\n * window.wallpaperPropertyListener = {\r\n *   applyUserProperties(props: Partial<MyProps>) {\r\n *     if (props.bgcolor) el.style.background = wallpaperColorToRgb(props.bgcolor.value);\r\n *     if (props.speed !== undefined) setSpeed(props.speed.value); // number ✓\r\n *   },\r\n * };\r\n */\r\nexport type WallpaperUserPropertiesOf<\r\n  T extends Record<string, WallpaperPropertyDefinition>,\r\n> = {\r\n  readonly [K in keyof T]: PropertyDefinitionToValue<T[K]>;\r\n};\r\n\r\n// ---------------------------------------------------------------------------\r\n// Vite plugin\r\n// ---------------------------------------------------------------------------\r\n\r\nexport interface WallpaperEnginePluginOptions {\r\n  /**\r\n   * Entry HTML file name relative to the project root.\r\n   * @default \"index.html\"\r\n   */\r\n  file?: string;\r\n  /** Wallpaper title shown in the Wallpaper Engine UI */\r\n  title: string;\r\n  /**\r\n   * Enable audio data delivery to `wallpaperRegisterAudioListener`.\r\n   * Wallpaper Engine can auto-detect this, but you can set it explicitly.\r\n   * @default false\r\n   */\r\n  supportsAudioProcessing?: boolean;\r\n  /**\r\n   * User-configurable properties exposed in the Wallpaper Engine properties panel.\r\n   * Keys become the property identifiers accessed in `applyUserProperties`.\r\n   *\r\n   * @example\r\n   * properties: {\r\n   *   bgcolor: colorProperty({ text: 'Background Color', value: '0 0 0' }),\r\n   *   speed:   sliderProperty({ text: 'Speed', value: 1, min: 0, max: 5 }),\r\n   * }\r\n   */\r\n  properties?: Record<string, WallpaperPropertyDefinition>;\r\n  /**\r\n   * Localization strings for property labels and combo option labels.\r\n   * Keys are BCP 47 language codes (e.g. `\"en-us\"`, `\"de-de\"`, `\"zh-chs\"`).\r\n   * Property labels that should be translated must start with `ui_`.\r\n   *\r\n   * @example\r\n   * localization: {\r\n   *   'en-us': { 'ui_bgcolor': 'Background Color' },\r\n   *   'de-de': { 'ui_bgcolor': 'Hintergrundfarbe' },\r\n   * }\r\n   */\r\n  localization?: WallpaperLocalization;\r\n  /**\r\n   * Enable the in-browser dev overlay during `vite dev`. The overlay stubs\r\n   * every `window.wallpaper*` global, renders a draggable panel to edit each\r\n   * property in real time, and lets you fire audio/media/plugin events\r\n   * manually — so wallpapers can be developed without round-tripping through\r\n   * the Wallpaper Engine host application.\r\n   *\r\n   * Disabled automatically for production builds regardless of this setting.\r\n   *\r\n   * @default true\r\n   */\r\n  devtools?: boolean;\r\n}\r\n\r\n/**\r\n * Vite plugin that auto-generates `project.json` into the build output.\r\n *\r\n * @example\r\n * // vite.config.ts\r\n * import { wallpaperEnginePlugin, colorProperty } from 'wallpaper-engine/plugin';\r\n *\r\n * export default defineConfig({\r\n *   plugins: [\r\n *     wallpaperEnginePlugin({\r\n *       title: 'My Wallpaper',\r\n *       properties: {\r\n *         bgcolor: colorProperty({ text: 'Background Color', value: '0 0 0' }),\r\n *       },\r\n *     }),\r\n *   ],\r\n * });\r\n */\r\nexport function wallpaperEnginePlugin(\r\n  options: WallpaperEnginePluginOptions,\r\n): Plugin {\r\n  const devtoolsEnabled = options.devtools !== false;\r\n  const VIRTUAL_ID = \"virtual:wallpaper-engine/devtools\";\r\n  const RESOLVED_ID = \"\\0\" + VIRTUAL_ID;\r\n  let isServe = false;\r\n  let cachedClientCode: string | undefined;\r\n  const loadClientCode = async (): Promise<string> => {\r\n    if (cachedClientCode !== undefined) return cachedClientCode;\r\n    // Reads the Vue UI bundle emitted by `vite build -c vite.devtools.config.ts`\r\n    // into `dist/plugin/devtools/client.js`. Imports are dynamic so this file\r\n    // stays browser-safe — property builders below are imported by user code.\r\n    const { readFileSync } = await import(\"node:fs\");\r\n    const { fileURLToPath } = await import(\"node:url\");\r\n    const url = new URL(\"./devtools/client.js\", import.meta.url);\r\n    cachedClientCode = readFileSync(fileURLToPath(url), \"utf8\");\r\n    return cachedClientCode;\r\n  };\r\n\r\n  return {\r\n    name: \"wallpaper-engine\",\r\n\r\n    configResolved(config) {\r\n      isServe = config.command === \"serve\";\r\n    },\r\n\r\n    configureServer(server) {\r\n      if (!devtoolsEnabled) return;\r\n      void Promise.all([import(\"node:fs\"), import(\"node:url\")]).then(\r\n        ([fs, { fileURLToPath }]) => {\r\n          const clientPath = fileURLToPath(\r\n            new URL(\"./devtools/client.js\", import.meta.url),\r\n          );\r\n          // Use stat-polling watchFile instead of chokidar: avoids Windows\r\n          // path-normalisation mismatches (forward vs back slashes) and works\r\n          // correctly across Bun workspace symlinks.\r\n          fs.watchFile(clientPath, { interval: 500 }, () => {\r\n            cachedClientCode = undefined;\r\n            const mod = server.moduleGraph.getModuleById(RESOLVED_ID);\r\n            if (mod) server.moduleGraph.invalidateModule(mod);\r\n            server.ws.send({ type: \"full-reload\" });\r\n          });\r\n          server.httpServer?.once(\"close\", () => {\r\n            fs.unwatchFile(clientPath);\r\n          });\r\n        },\r\n      );\r\n    },\r\n\r\n    resolveId(id) {\r\n      if (id === VIRTUAL_ID) return RESOLVED_ID;\r\n      return null;\r\n    },\r\n\r\n    async load(id) {\r\n      if (id !== RESOLVED_ID) return null;\r\n      const properties = options.properties\r\n        ? assignIndices(options.properties)\r\n        : {};\r\n      const cfg = {\r\n        title: options.title,\r\n        properties,\r\n        localization: options.localization ?? {},\r\n      };\r\n      return (\r\n        \"window.__WE_DEVTOOLS_CONFIG__ = \" +\r\n        JSON.stringify(cfg) +\r\n        \";\\n\" +\r\n        (await loadClientCode())\r\n      );\r\n    },\r\n\r\n    transformIndexHtml() {\r\n      if (!isServe || !devtoolsEnabled) return;\r\n      return [\r\n        {\r\n          tag: \"script\",\r\n          attrs: { type: \"module\", src: \"/@id/\" + VIRTUAL_ID },\r\n          injectTo: \"head-prepend\",\r\n        },\r\n      ];\r\n    },\r\n\r\n    generateBundle() {\r\n      const properties = options.properties\r\n        ? assignIndices(options.properties)\r\n        : undefined;\r\n\r\n      const general: WallpaperProjectGeneral = {};\r\n      if (properties) general.properties = properties;\r\n      if (options.localization) general.localization = options.localization;\r\n\r\n      const project: WallpaperProject = {\r\n        file: options.file ?? \"index.html\",\r\n        title: options.title,\r\n        type: \"web\",\r\n      };\r\n\r\n      if (options.supportsAudioProcessing) {\r\n        project.supportsaudioprocessing = true;\r\n      }\r\n\r\n      if (Object.keys(general).length > 0) {\r\n        project.general = general;\r\n      }\r\n\r\n      this.emitFile({\r\n        type: \"asset\",\r\n        fileName: \"project.json\",\r\n        source: JSON.stringify(project, null, \"\\t\"),\r\n      });\r\n    },\r\n  };\r\n}\r\n\r\n// ---------------------------------------------------------------------------\r\n// Internal helpers\r\n// ---------------------------------------------------------------------------\r\n\r\n/**\r\n * Auto-assigns `index` and `order` to any properties that don't already have\r\n * them, based on their insertion order in the record.\r\n */\r\nfunction assignIndices(\r\n  properties: Record<string, WallpaperPropertyDefinition>,\r\n): Record<string, WallpaperPropertyDefinition> {\r\n  const result: Record<string, WallpaperPropertyDefinition> = {};\r\n  let i = 0;\r\n\r\n  for (const [key, prop] of Object.entries(properties)) {\r\n    result[key] = {\r\n      index: i,\r\n      order: i,\r\n      ...prop,\r\n    };\r\n    i++;\r\n  }\r\n\r\n  return result;\r\n}\r\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "wallpaper-engine",
+  "version": "1.0.0",
+  "description": "TypeScript types, Vite plugin, and runtime helpers for Wallpaper Engine web wallpapers",
+  "keywords": [
+    "wallpaper-engine",
+    "wallpaper engine",
+    "web wallpaper",
+    "vite plugin",
+    "typescript"
+  ],
+  "license": "MIT",
+  "author": "ShadowNineX",
+  "homepage": "https://github.com/ShadowNineX/wallpaper-engine#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShadowNineX/wallpaper-engine.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ShadowNineX/wallpaper-engine/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./plugin": {
+      "types": "./dist/plugin/index.d.ts",
+      "import": "./dist/plugin/index.js"
+    },
+    "./helpers": {
+      "types": "./dist/helpers.d.ts",
+      "import": "./dist/helpers.js",
+      "require": "./dist/helpers.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "build:lib": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "prepublishOnly": "bun run --cwd ../.. build"
+  },
+  "peerDependencies": {
+    "vite": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.6",
+    "tsup": "^8.5.1",
+    "vite": "^8.0.13",
+    "vitest": "^4.1.6"
+  }
+}