From f9cd5bcb407cf6e3044eaec09268c8833e1099de Mon Sep 17 00:00:00 2001
From: Baoshuo <i@baoshuo.ren>
Date: Wed, 22 Jul 2026 03:07:33 +0800
Subject: [PATCH] ui-next: refactor plugin loader (#1190)

---
 examples/plugins/ui-next-plugin/index.ts      | 29 +++++++
 examples/plugins/ui-next-plugin/package.json  |  3 +-
 examples/plugins/ui-next-plugin/ui/index.tsx  |  9 +-
 .../ui-next-plugin/ui/pages/example_css.tsx   | 12 +++
 .../ui-next-plugin/ui/pages/example_home.tsx  | 14 +++
 examples/plugins/ui-next-plugin/ui/styles.css | 13 +++
 .../ui-next-plugin/ui/styles.module.css       | 22 +++++
 packages/ui-next/api.ts                       |  2 +
 packages/ui-next/css.d.ts                     |  6 ++
 packages/ui-next/index.ts                     | 86 ++++++++++++++++---
 packages/ui-next/package.json                 |  1 +
 packages/ui-next/vite.config.ts               |  1 +
 12 files changed, 181 insertions(+), 17 deletions(-)
 create mode 100644 examples/plugins/ui-next-plugin/index.ts
 create mode 100644 examples/plugins/ui-next-plugin/ui/pages/example_css.tsx
 create mode 100644 examples/plugins/ui-next-plugin/ui/pages/example_home.tsx
 create mode 100644 examples/plugins/ui-next-plugin/ui/styles.css
 create mode 100644 examples/plugins/ui-next-plugin/ui/styles.module.css
 create mode 100644 packages/ui-next/css.d.ts

diff --git a/examples/plugins/ui-next-plugin/index.ts b/examples/plugins/ui-next-plugin/index.ts
new file mode 100644
index 000000000..10384ad31
--- /dev/null
+++ b/examples/plugins/ui-next-plugin/index.ts
@@ -0,0 +1,29 @@
+import { Context, Handler } from 'hydrooj';
+
+// Server side of the example plugin. It registers a couple of routes whose
+// handlers set a `template`; with @hydrooj/ui-next installed the `next` renderer
+// (priority 100) wins for every template, ignores the template file, and injects
+// the route/template name into the SPA shell. The client then renders the page
+// registered under `page:<template without .html>` (falling back to `page:<route name>`).
+
+class ExampleHomeHandler extends Handler {
+    async get() {
+        // Stem (`example_home`) must match the slot registered in ui/index.tsx.
+        this.response.template = 'example_home.html';
+        // response.body is forwarded to the page as `args` (see usePageData).
+        this.response.body = { message: 'Hello from the ui-next example plugin server side!' };
+    }
+}
+
+class ExampleCssHandler extends Handler {
+    async get() {
+        this.response.template = 'example_css.html';
+        this.response.body = {};
+    }
+}
+
+export async function apply(ctx: Context) {
+    // A couple of test routes to host the example pages.
+    ctx.Route('example_home', '/example', ExampleHomeHandler);
+    ctx.Route('example_css', '/example/css', ExampleCssHandler);
+}
diff --git a/examples/plugins/ui-next-plugin/package.json b/examples/plugins/ui-next-plugin/package.json
index 7062530fb..174d58ca8 100644
--- a/examples/plugins/ui-next-plugin/package.json
+++ b/examples/plugins/ui-next-plugin/package.json
@@ -7,6 +7,7 @@
     "cli": false
   },
   "dependencies": {
-    "@hydrooj/ui-next": "workspace:*"
+    "@hydrooj/ui-next": "workspace:*",
+    "hydrooj": "workspace:*"
   }
 }
diff --git a/examples/plugins/ui-next-plugin/ui/index.tsx b/examples/plugins/ui-next-plugin/ui/index.tsx
index f14312624..8a92c4d5d 100644
--- a/examples/plugins/ui-next-plugin/ui/index.tsx
+++ b/examples/plugins/ui-next-plugin/ui/index.tsx
@@ -1,9 +1,8 @@
 import type { PluginAPI } from '@hydrooj/ui-next';
 
 export function setup(api: PluginAPI) {
-    api.before('page:app', () => {
-        console.log('before app');
-        // throw new Error('test error boundary in before interceptor');
-        return <div>before app via @hydrooj/ui-next-plugin-sample</div>;
-    });
+    // (2) Page registration — slot names match the server route names / template stems
+    // registered in ../index.ts. Pages are lazy-loaded on demand.
+    api.registerPage('example_home', () => import('./pages/example_home'));
+    api.registerPage('example_css', () => import('./pages/example_css'));
 }
diff --git a/examples/plugins/ui-next-plugin/ui/pages/example_css.tsx b/examples/plugins/ui-next-plugin/ui/pages/example_css.tsx
new file mode 100644
index 000000000..674d9c38f
--- /dev/null
+++ b/examples/plugins/ui-next-plugin/ui/pages/example_css.tsx
@@ -0,0 +1,12 @@
+import { Link } from '@hydrooj/ui-next';
+import styles from '../styles.module.css'; // (1) CSS module — scoped class names
+
+export default function ExampleCss() {
+    return (
+        <div className={styles.card}>
+            <span className={styles.badge}>CSS module</span>
+            <h2 className={styles.title}>Scoped class names</h2>
+            <p><Link to="example_home">← Back</Link></p>
+        </div>
+    );
+}
diff --git a/examples/plugins/ui-next-plugin/ui/pages/example_home.tsx b/examples/plugins/ui-next-plugin/ui/pages/example_home.tsx
new file mode 100644
index 000000000..cd40c953b
--- /dev/null
+++ b/examples/plugins/ui-next-plugin/ui/pages/example_home.tsx
@@ -0,0 +1,14 @@
+import '../styles.css'; // (3) plain CSS import — applied globally when this page loads
+
+import { Link, usePageData } from '@hydrooj/ui-next';
+
+export default function ExampleHome() {
+    const { args } = usePageData(); // args carries the handler's response.body
+    return (
+        <div className="example-page">
+            <h1>ui-next example plugin</h1>
+            <p>{args.message as string}</p>
+            <Link to="example_css">See the CSS-module demo →</Link>
+        </div>
+    );
+}
diff --git a/examples/plugins/ui-next-plugin/ui/styles.css b/examples/plugins/ui-next-plugin/ui/styles.css
new file mode 100644
index 000000000..daebf1c22
--- /dev/null
+++ b/examples/plugins/ui-next-plugin/ui/styles.css
@@ -0,0 +1,13 @@
+/* Imported via `import './styles.css'` — bundled and injected globally as a <style>. */
+.example-page {
+    padding: 24px;
+    max-width: 720px;
+    margin: 0 auto;
+}
+.example-page h1 {
+    font-size: 24px;
+    font-weight: 700;
+}
+.example-page a {
+    color: #4f46e5;
+}
diff --git a/examples/plugins/ui-next-plugin/ui/styles.module.css b/examples/plugins/ui-next-plugin/ui/styles.module.css
new file mode 100644
index 000000000..af6e89103
--- /dev/null
+++ b/examples/plugins/ui-next-plugin/ui/styles.module.css
@@ -0,0 +1,22 @@
+/* Imported via `import styles from './styles.module.css'`; class names are hashed/scoped,
+   accessed as styles.card / styles.badge / styles.title. */
+.card {
+    padding: 16px;
+    border: 1px solid #e5e7eb;
+    border-radius: 8px;
+    max-width: 720px;
+    margin: 24px auto;
+}
+.badge {
+    display: inline-block;
+    padding: 2px 8px;
+    border-radius: 4px;
+    background: #4f46e5;
+    color: #fff;
+    font-size: 12px;
+}
+.title {
+    margin-top: 8px;
+    font-size: 20px;
+    font-weight: 700;
+}
diff --git a/packages/ui-next/api.ts b/packages/ui-next/api.ts
index 893c061ee..417ffc565 100644
--- a/packages/ui-next/api.ts
+++ b/packages/ui-next/api.ts
@@ -1 +1,3 @@
+/// <reference path="./css.d.ts" />
+
 export * from './src/api';
diff --git a/packages/ui-next/css.d.ts b/packages/ui-next/css.d.ts
new file mode 100644
index 000000000..013667c40
--- /dev/null
+++ b/packages/ui-next/css.d.ts
@@ -0,0 +1,6 @@
+declare module '*.css';
+
+declare module '*.module.css' {
+    const classes: Record<string, string>;
+    export default classes;
+}
diff --git a/packages/ui-next/index.ts b/packages/ui-next/index.ts
index adf49f41f..2f2dc72a0 100644
--- a/packages/ui-next/index.ts
+++ b/packages/ui-next/index.ts
@@ -1,4 +1,3 @@
-import crypto from 'crypto';
 import fs from 'fs';
 import path from 'path';
 import esbuild from 'esbuild';
@@ -7,7 +6,7 @@ import { createServer, type Plugin } from 'vite';
 import { serializer } from '@hydrooj/framework';
 import {
     Context, Handler, Logger,
-    NotFoundError, param, size, Types,
+    NotFoundError, param, sha1, size, Types,
 } from 'hydrooj';
 
 const logger = new Logger('ui-next');
@@ -100,12 +99,25 @@ const federationPlugin: esbuild.Plugin = {
 const vfs: Record<string, string> = {};
 const hashes: Record<string, string> = {};
 
+const applyCss = (css: string) => `
+(() => {
+  const style = document.createElement('style');
+  style.textContent = ${JSON.stringify(css)};
+  document.head.appendChild(style);
+})();
+`;
+
+function addFile(name: string, content: string) {
+    vfs[name] = content;
+    hashes[name] = sha1(content).substring(0, 8);
+}
+
 class UiNextConstantHandler extends Handler {
     noCheckPermView = true;
 
     @param('name', Types.Filename)
     async all(domainId: string, name: string) {
-        if (!vfs[name]) throw new NotFoundError(name);
+        if (!(name in vfs)) throw new NotFoundError(name);
         this.response.type = 'application/javascript';
         this.response.body = vfs[name];
         this.response.addHeader('ETag', hashes[name]);
@@ -118,9 +130,23 @@ export async function buildPlugins() {
     let totalSize = 0;
     const entries = getAddonEntries();
 
+    const newPluginFiles = new Set<string>();
+    const emit = (name: string, content: string) => {
+        addFile(name, content);
+        newPluginFiles.add(name);
+    };
+    const purge = () => {
+        for (const key of Object.keys(vfs)) {
+            if (!newPluginFiles.has(key)) {
+                delete vfs[key];
+                delete hashes[key];
+            }
+        }
+    };
+
     if (!Object.keys(entries).length) {
-        vfs['plugins.js'] = 'window.__hydroPlugins = [];';
-        hashes['plugins.js'] = '00000000';
+        emit('plugins.js', 'window.__hydroPlugins = [];');
+        purge();
         logger.info('No plugins to build');
         return;
     }
@@ -132,11 +158,18 @@ export async function buildPlugins() {
                     ...Object.entries(entries).map(([_, e], i) => `import * as plugin${i} from '${e}';`),
                     `window.__hydroPlugins = [${Object.entries(entries).map(([n], i) => `{ name: '${n}', ...plugin${i} }`).join(', ')}];`,
                 ].join('\n'),
+                sourcefile: 'plugins.ts',
                 resolveDir: process.cwd(),
                 loader: 'ts',
             },
             bundle: true,
-            format: 'iife',
+            format: 'esm',
+            splitting: true,
+            outdir: 'plugins-dist',
+            entryNames: 'plugins',
+            chunkNames: 'chunk-[hash]',
+            assetNames: 'asset-[hash]',
+            metafile: true,
             write: false,
             target: ['chrome90'],
             plugins: [federationPlugin],
@@ -145,11 +178,42 @@ export async function buildPlugins() {
             jsxImportSource: 'react',
         });
         if (result.errors.length) logger.error('Plugin build errors: %o', result.errors);
-        const content = result.outputFiles?.[0]?.text || 'window.__hydroPlugins = [];';
-        vfs['plugins.js'] = content;
-        hashes['plugins.js'] = crypto.createHash('sha1').update(content).digest('hex').substring(0, 8);
-        totalSize += content.length;
-        logger.success('Plugins built in %dms (%d entries, %s)', Date.now() - start, entries.length, size(totalSize));
+
+        const cssText = new Map<string, string>();
+        for (const f of result.outputFiles) {
+            if (f.path.endsWith('.css')) cssText.set(f.path, f.text);
+        }
+
+        const cssForJs = new Map<string, string>();
+        const claimed = new Set<string>();
+        for (const [rel, meta] of Object.entries(result.metafile.outputs)) {
+            if (!meta.cssBundle) continue;
+            const css = path.resolve(meta.cssBundle);
+            cssForJs.set(path.resolve(rel), css);
+            claimed.add(css);
+        }
+
+        let unclaimedCss = '';
+        for (const [abs, text] of cssText) {
+            if (!claimed.has(abs)) unclaimedCss += text;
+        }
+
+        for (const f of result.outputFiles) {
+            if (f.path.endsWith('.css')) continue;
+
+            const name = path.basename(f.path);
+            let content = f.text;
+
+            const css = cssText.get(cssForJs.get(f.path) ?? '');
+            if (css) content = applyCss(css) + content;
+            if (name === 'plugins.js' && unclaimedCss) content = applyCss(unclaimedCss) + content;
+
+            totalSize += content.length;
+            emit(name, content);
+        }
+
+        purge();
+        logger.success('Plugins built in %dms (%d entries, %s)', Date.now() - start, Object.keys(entries).length, size(totalSize));
     } catch (e) {
         logger.error('Plugin build failed: %o', e);
     }
diff --git a/packages/ui-next/package.json b/packages/ui-next/package.json
index d780bcc81..85f612c35 100644
--- a/packages/ui-next/package.json
+++ b/packages/ui-next/package.json
@@ -13,6 +13,7 @@
   "files": [
     "index.ts",
     "api.ts",
+    "css.d.ts",
     "src/",
     "index.html",
     "public/",
diff --git a/packages/ui-next/vite.config.ts b/packages/ui-next/vite.config.ts
index 7e32f6ae8..539cad66a 100644
--- a/packages/ui-next/vite.config.ts
+++ b/packages/ui-next/vite.config.ts
@@ -9,6 +9,7 @@ export default defineConfig({
     resolve: {
         alias: {
             '@': path.resolve(__dirname, 'src'),
+            '@hydrooj/ui-next': path.resolve(__dirname, 'src/api.ts'),
         },
     },
     publicDir: 'pub',