vite-plugin-turbowarp-packager 0.1.0

package/README.md

@@ -0,0 +1,71 @@
+# vite-plugin-turbowarp-packager
+
+A Vite plugin that uses `@turbowarp/packager` to generate TurboWarp-ready HTML from a `.sb3` file.  
+During build, it outputs `dist/turbowarp-packager.html`.
+
+## Installation
+
+```bash
+bun add -D vite-plugin-turbowarp-packager
+```
+
+## Usage
+
+### Use with `hikkaku/vite` (recommended)
+
+The `hikkaku` plugin automatically sets the output path for `project.sb3`.
+
+```ts
+import hikkaku from 'hikkaku/vite'
+import { defineConfig } from 'vite-plus'
+import { pluginTurbowarpPackager } from 'vite-plugin-turbowarp-packager'
+
+export default defineConfig({
+  plugins: [
+    hikkaku({
+      entry: 'src.ts',
+    }),
+    pluginTurbowarpPackager(),
+  ],
+})
+```
+
+When using both plugins, place `hikkaku(...)` before `pluginTurbowarpPackager(...)`.
+
+### Set `sb3Entry` manually
+
+If your `.sb3` is generated by another process, set `sb3Entry` directly.
+
+```ts
+import { defineConfig } from 'vite-plus'
+import { pluginTurbowarpPackager } from 'vite-plugin-turbowarp-packager'
+
+export default defineConfig({
+  plugins: [
+    pluginTurbowarpPackager({
+      sb3Entry: 'dist/project.sb3',
+      packagerOptions: {
+        turbo: true,
+      },
+    }),
+  ],
+})
+```
+
+## Options
+
+```ts
+interface TurbowarpPackagerOptions {
+  sb3Entry?: string
+  packagerOptions?: Partial<PackagerOptions>
+}
+```
+
+- `sb3Entry`: Path to the `.sb3` file to package. Build fails if omitted.
+- `packagerOptions`: Options passed to `@turbowarp/packager`.
+
+## Limitations
+
+- `packagerOptions.target` currently supports only `html`.
+- Output filename is fixed to `turbowarp-packager.html`.
+- This plugin is intended for build-time packaging (not dev-server conversion).

package/dist/index.d.mts

@@ -0,0 +1,11 @@
+import { PackagerOptions } from "@turbowarp/packager";
+import { PluginOption } from "vite";
+
+//#region src/index.d.ts
+interface TurbowarpPackagerOptions {
+  sb3Entry?: string;
+  packagerOptions?: Partial<PackagerOptions>;
+}
+declare const pluginTurbowarpPackager: (options?: TurbowarpPackagerOptions) => PluginOption;
+//#endregion
+export { TurbowarpPackagerOptions, pluginTurbowarpPackager };

package/dist/index.mjs

@@ -0,0 +1,80 @@
+import { readFile } from "node:fs/promises";
+
+//#region src/packager.ts
+async function loadPackager() {
+	const packagerModule = await import("@turbowarp/packager");
+	const Packager = packagerModule.Packager ?? packagerModule.packager?.Packager ?? packagerModule.default?.Packager ?? packagerModule.default?.packager?.Packager;
+	const loadProject = packagerModule.loadProject ?? packagerModule.packager?.loadProject ?? packagerModule.default?.loadProject ?? packagerModule.default?.packager?.loadProject;
+	if (!Packager || !loadProject) throw new Error(`Could not find Packager or loadProject in @turbowarp/packager module. Keys: ${Object.keys(packagerModule)}`);
+	return {
+		Packager,
+		loadProject
+	};
+}
+
+//#endregion
+//#region src/index.ts
+const VIRTUAL_MODULE_IDS = {
+	html: "virtual:turbowarp-packager.html",
+	js: "virtual:turbowarp-packager.js"
+};
+const pluginTurbowarpPackager = (options) => {
+	let packedData = null;
+	const decoder = new TextDecoder();
+	const pack = async () => {
+		if (packedData) return packedData;
+		const sb3Entry = options?.sb3Entry;
+		if (!sb3Entry) throw new Error("sb3Entry is not set in TurbowarpPackagerOptions.");
+		const { loadProject, Packager } = await loadPackager();
+		const project = await loadProject(await readFile(sb3Entry));
+		const packager = new Packager();
+		const resolvedPackagerOptions = Object.assign({}, packager.options, { target: "html" }, options?.packagerOptions ?? {});
+		packager.options = resolvedPackagerOptions;
+		packager.project = project;
+		if (resolvedPackagerOptions.target !== "html") throw new Error(`Currently ${resolvedPackagerOptions.target} target is not supported in Vite plugin, only 'html' target is supported.`);
+		const packageResult = await packager.package();
+		const html = typeof packageResult.data === "string" ? packageResult.data : decoder.decode(packageResult.data);
+		packedData = html;
+		return html;
+	};
+	return {
+		name: "vite-plugin-turbowarp-packager",
+		api: { setEntry(sb3Entry) {
+			options = {
+				...options,
+				sb3Entry
+			};
+		} },
+		config(_config, _env) {
+			if (!options?.sb3Entry) throw new Error("sb3Entry is not set in TurbowarpPackagerOptions.");
+			return {
+				environments: { turbowarpPackager: {
+					build: { rolldownOptions: {
+						input: VIRTUAL_MODULE_IDS.html,
+						output: { entryFileNames: "turbowarp-packager.html" }
+					} },
+					consumer: "client"
+				} },
+				builder: {}
+			};
+		},
+		async buildApp(builder) {
+			const env = builder.environments.turbowarpPackager;
+			if (!env) throw new Error("Turbowarp Packager environment is not configured.");
+			await builder.build(env);
+		},
+		resolveId(source) {
+			if (source === VIRTUAL_MODULE_IDS.html) return source;
+		},
+		async load(id) {
+			if (id === VIRTUAL_MODULE_IDS.html) {
+				const packed = await pack();
+				if (!packed) throw new Error("Packing failed.");
+				return { code: packed };
+			}
+		}
+	};
+};
+
+//#endregion
+export { pluginTurbowarpPackager };

package/example/src.ts

@@ -0,0 +1,12 @@
+import { Project } from 'hikkaku'
+import { say, whenFlagClicked } from 'hikkaku/blocks'
+
+const project = new Project()
+
+project.stage.run(() => {
+  whenFlagClicked(() => {
+    say('Hello, Turbowarp Packager!')
+  })
+})
+
+export default project

package/example/vite.config.ts

@@ -0,0 +1,15 @@
+import hikkaku from 'hikkaku/vite'
+import { defineConfig } from 'vite-plus'
+import { pluginTurbowarpPackager } from '../src'
+
+export default defineConfig({
+  plugins: [
+    hikkaku({
+      entry: 'src.ts',
+    }),
+    pluginTurbowarpPackager(),
+  ],
+  build: {
+    minify: false,
+  },
+})

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "vite-plugin-turbowarp-packager",
+  "type": "module",
+  "version": "0.1.0",
+  "devDependencies": {
+    "@types/bun": "latest",
+    "vite-plus": "^0.0.0-3262bda4.20260210-0221"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.,ts"
+    }
+  },
+  "scripts": {
+    "build": "vp pack"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@turbowarp/packager": "^3.11.0",
+    "fflate": "^0.8.2",
+    "hikkaku": "0.1.9",
+    "vite": "8.0.0-beta.13"
+  }
+}

package/src/index.ts

@@ -0,0 +1,115 @@
+import { readFile } from 'node:fs/promises'
+import type { PackagerOptions } from '@turbowarp/packager'
+import type { PluginOption } from 'vite'
+import { loadPackager } from './packager'
+
+const VIRTUAL_MODULE_IDS = {
+  html: 'virtual:turbowarp-packager.html',
+  js: 'virtual:turbowarp-packager.js',
+} as const
+
+export interface TurbowarpPackagerOptions {
+  sb3Entry?: string
+  packagerOptions?: Partial<PackagerOptions>
+}
+
+export const pluginTurbowarpPackager = (
+  options?: TurbowarpPackagerOptions,
+): PluginOption => {
+  let packedData: string | null = null
+  const decoder = new TextDecoder()
+  const pack = async () => {
+    if (packedData) {
+      return packedData
+    }
+    const sb3Entry = options?.sb3Entry
+    if (!sb3Entry) {
+      throw new Error('sb3Entry is not set in TurbowarpPackagerOptions.')
+    }
+    const { loadProject, Packager } = await loadPackager()
+    const sb3 = await readFile(sb3Entry)
+
+    const project = await loadProject(sb3)
+    const packager = new Packager()
+    const resolvedPackagerOptions = Object.assign(
+      {},
+      packager.options,
+      {
+        target: 'html',
+      },
+      options?.packagerOptions ?? {},
+    )
+    packager.options = resolvedPackagerOptions
+    packager.project = project
+    if (resolvedPackagerOptions.target !== 'html') {
+      throw new Error(
+        `Currently ${resolvedPackagerOptions.target} target is not supported in Vite plugin, only 'html' target is supported.`,
+      )
+    }
+    const packageResult = await packager.package()
+
+    const html =
+      typeof packageResult.data === 'string'
+        ? packageResult.data
+        : decoder.decode(packageResult.data)
+    packedData = html
+    return html
+  }
+  return {
+    name: 'vite-plugin-turbowarp-packager',
+    api: {
+      setEntry(sb3Entry: string) {
+        options = {
+          ...options,
+          sb3Entry,
+        }
+      },
+    },
+    config(_config, _env) {
+      const sb3Entry = options?.sb3Entry
+      if (!sb3Entry) {
+        throw new Error('sb3Entry is not set in TurbowarpPackagerOptions.')
+      }
+      return {
+        environments: {
+          turbowarpPackager: {
+            build: {
+              rolldownOptions: {
+                input: VIRTUAL_MODULE_IDS.html,
+                output: {
+                  entryFileNames: 'turbowarp-packager.html',
+                },
+              },
+            },
+            consumer: 'client',
+          },
+        },
+        builder: {},
+      }
+    },
+    async buildApp(builder) {
+      const env = builder.environments.turbowarpPackager
+      if (!env) {
+        throw new Error('Turbowarp Packager environment is not configured.')
+      }
+      await builder.build(env)
+    },
+    resolveId(source) {
+      if (source === VIRTUAL_MODULE_IDS.html) {
+        return source
+      }
+    },
+    async load(id) {
+      if (id === VIRTUAL_MODULE_IDS.html) {
+        const packed = await pack()
+        if (!packed) {
+          throw new Error('Packing failed.')
+        }
+
+        return {
+          code: packed,
+        }
+      }
+    },
+  }
+}

package/src/packager.d.ts

@@ -0,0 +1,130 @@
+declare module '@turbowarp/packager' {
+  export interface PackagerOptions {
+    turbo: boolean
+    interpolation: boolean
+    framerate: number
+    highQualityPen: boolean
+    maxClones: number
+    fencing: boolean
+    miscLimits: boolean
+    stageWidth: number
+    stageHeight: number
+    resizeMode: 'preserve-ratio' | 'stretch' | 'none'
+    autoplay: boolean
+    username: string
+    closeWhenStopped: boolean
+    projectId: string
+    custom: {
+      css: string
+      js: string
+    }
+    appearance: {
+      background: string
+      foreground: string
+      accent: string
+    }
+    loadingScreen: {
+      progressBar: boolean
+      text: string
+      imageMode: 'normal' | 'stretch'
+      image: unknown | null
+    }
+    controls: {
+      greenFlag: {
+        enabled: boolean
+      }
+      stopAll: {
+        enabled: boolean
+      }
+      fullscreen: {
+        enabled: boolean
+      }
+      pause: {
+        enabled: boolean
+      }
+    }
+    monitors: {
+      editableLists: boolean
+      variableColor: string
+      listColor: string
+    }
+    compiler: {
+      enabled: boolean
+      warpTimer: boolean
+    }
+    packagedRuntime: boolean
+    target:
+      | 'html'
+      | 'zip'
+      | 'zip-one-asset'
+      | 'nwjs-win32'
+      | 'nwjs-win64'
+      | 'nwjs-mac'
+      | 'nwjs-linux-x64'
+      | 'electron-win32'
+      | 'electron-win64'
+      | 'electron-win-arm'
+      | 'electron-mac'
+      | 'electron-linux64'
+      | 'electron-linux-arm32'
+      | 'electron-linux-arm64'
+      | 'webview-mac'
+    app: {
+      icon: unknown | null
+      packageName: string
+      windowTitle: string
+      windowMode: 'window' | 'maximize' | 'fullscreen'
+      version: string
+      escapeBehavior:
+        | 'unfullscreen-only'
+        | 'unfullscreen-or-exit'
+        | 'exit-only'
+        | 'none'
+      windowControls: 'default' | 'frameless'
+      backgroundThrottling: boolean
+    }
+    chunks: {
+      gamepad: boolean
+      pointerlock: boolean
+    }
+    cloudVariables: {
+      mode: 'ws' | 'local' | 'custom'
+      cloudHost: string | string[]
+      custom: Record<string, 'ws' | 'local'>
+      specialCloudBehaviors: boolean
+      unsafeCloudBehaviors: boolean
+    }
+    cursor: {
+      type: 'auto' | 'none' | 'custom'
+      custom: unknown | null
+      center: {
+        x: number
+        y: number
+      }
+    }
+    steamworks: {
+      appId: string
+      onError: 'ignore' | 'warning' | 'error'
+    }
+    extensions: string[]
+    bakeExtensions: boolean
+    maxTextureDimension: number
+  }
+
+  export class Packager {
+    constructor()
+    options: PackagerOptions
+    project: unknown
+    loadProject(data: ArrayBuffer | Uint8Array | ArrayBufferLike): Promise<void>
+    package(): Promise<{ data: Uint8Array | string; type: string }>
+  }
+
+  export function loadProject(
+    data: ArrayBuffer | Uint8Array | ArrayBufferLike,
+  ): Promise<unknown>
+
+  export const packager: {
+    Packager: typeof Packager
+    loadProject: typeof loadProject
+  }
+}

package/src/packager.ts

@@ -0,0 +1,28 @@
+/// <reference path="./packager.d.ts" />
+
+export async function loadPackager() {
+  const packagerModule = await import('@turbowarp/packager')
+  const Packager =
+    packagerModule.Packager ??
+    packagerModule.packager?.Packager ??
+    (packagerModule as { default: { Packager: unknown } }).default?.Packager ??
+    (packagerModule as { default: { packager: { Packager: unknown } } }).default
+      ?.packager?.Packager
+  const loadProject =
+    packagerModule.loadProject ??
+    packagerModule.packager?.loadProject ??
+    (packagerModule as { default: { loadProject: unknown } }).default
+      ?.loadProject ??
+    (packagerModule as { default: { packager: { loadProject: unknown } } })
+      .default?.packager?.loadProject
+
+  if (!Packager || !loadProject) {
+    throw new Error(
+      `Could not find Packager or loadProject in @turbowarp/packager module. Keys: ${Object.keys(
+        packagerModule,
+      )}`,
+    )
+  }
+
+  return { Packager, loadProject }
+}

package/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}

package/vite.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vite-plus'
+
+export default defineConfig({
+  pack: {
+    entry: 'src/index.ts',
+    dts: true,
+  },
+})