gamekit777 0.1.0

package/vite-config/index.js

@@ -0,0 +1,207 @@
+// dist-npm/vite-config/index.ts
+import path from "node:path";
+import { defineConfig } from "vite";
+import { svelte } from "@sveltejs/vite-plugin-svelte";
+
+// dist-npm/vite-config/meta.ts
+var ORIENTATIONS = ["portrait", "landscape", "any"];
+function normalizeMeta(m) {
+  for (const k of ["id", "title", "version"]) {
+    if (!m[k] || typeof m[k] !== "string")
+      throw new Error(`game.meta.json 缺少 ${k}`);
+  }
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(m.id)) {
+    throw new Error(`game.meta.json 的 id "${m.id}" 要是小写短横线形式——它同时是输出目录名`);
+  }
+  if (m.orientation !== undefined && !ORIENTATIONS.includes(m.orientation)) {
+    throw new Error(`game.meta.json 的 orientation "${m.orientation}" 无效，只能是 ${ORIENTATIONS.join(" / ")}`);
+  }
+  if (m.aspect !== undefined && !/^\d+(\.\d+)?:\d+(\.\d+)?$/.test(m.aspect)) {
+    throw new Error(`game.meta.json 的 aspect "${m.aspect}" 无效，形如 "16:10"`);
+  }
+  return { ...m, orientation: m.orientation };
+}
+
+// dist-npm/vite-config/manifest.ts
+var TYPE_BY_EXT = {
+  jpg: "image",
+  jpeg: "image",
+  png: "image",
+  webp: "image",
+  avif: "image",
+  svg: "image",
+  gif: "image",
+  mp3: "audio",
+  ogg: "audio",
+  wav: "audio",
+  m4a: "audio",
+  woff: "font",
+  woff2: "font",
+  ttf: "font",
+  json: "json",
+  mp4: "video",
+  webm: "video"
+};
+var CRITICAL_BUDGET = 1500000;
+function gameManifest(opts) {
+  const { meta, emitCssFile = false } = opts;
+  return {
+    name: "gamekit:manifest",
+    enforce: "post",
+    generateBundle: {
+      order: "post",
+      handler(_o, bundle) {
+        const assets = [];
+        for (const file of Object.values(bundle)) {
+          if (file.type !== "asset")
+            continue;
+          const a = file;
+          if (a.fileName.endsWith(".css"))
+            continue;
+          const orig = (a.originalFileName ?? "").replace(/\\/g, "/");
+          const m = /src\/assets\/(critical|lazy)\/(.+)$/.exec(orig);
+          const priority = m?.[1] ?? "critical";
+          const key = m ? `${m[1]}/${m[2]}` : a.fileName;
+          const ext = a.fileName.split(".").pop().toLowerCase();
+          const src = a.source;
+          assets.push({
+            key,
+            path: a.fileName,
+            type: TYPE_BY_EXT[ext] ?? "binary",
+            bytes: typeof src === "string" ? Buffer.byteLength(src) : src.byteLength,
+            priority
+          });
+        }
+        assets.sort((x, y) => x.priority === y.priority ? x.key.localeCompare(y.key) : x.priority === "critical" ? -1 : 1);
+        const cssAsset = Object.values(bundle).find((f) => f.type === "asset" && f.fileName.endsWith(".css"));
+        const indexJs = bundle["index.js"];
+        let cssInlined = false;
+        if (cssAsset && indexJs && !emitCssFile) {
+          const css = String(cssAsset.source);
+          if (/url\(\s*['"]?(?!data:|#)/.test(css)) {
+            this.warn(`[${meta.id}] CSS 里有 url()，内联注入后会相对 document 解析而错位。` + `改用 <img> 引用资源，或给 defineGameConfig 传 emitCssFile: true`);
+          }
+          indexJs.code = `(function(){var s=document.createElement('style');` + `s.setAttribute('data-game',${JSON.stringify(meta.id)});` + `s.textContent=${JSON.stringify(css)};` + `document.head.appendChild(s)})();
+` + indexJs.code;
+          delete bundle[cssAsset.fileName];
+          cssInlined = true;
+        }
+        const manifest = {
+          id: meta.id,
+          version: meta.version,
+          generatedAt: new Date().toISOString(),
+          entry: "index.js",
+          css: cssInlined ? null : cssAsset?.fileName ?? null,
+          totalBytes: assets.reduce((s, a) => s + a.bytes, 0),
+          criticalBytes: assets.filter((a) => a.priority === "critical").reduce((s, a) => s + a.bytes, 0),
+          assets
+        };
+        this.emitFile({ type: "asset", fileName: "manifest.json", source: JSON.stringify(manifest, null, 2) });
+        this.emitFile({ type: "asset", fileName: "meta.json", source: JSON.stringify(meta, null, 2) });
+        if (!cssAsset && !emitCssFile) {
+          this.warn(`[${meta.id}] 没找到 CSS 产物。要么游戏真的没样式，` + `要么这个插件跑得太早（应当 enforce:'post' + order:'post'）`);
+        }
+        if (manifest.criticalBytes > CRITICAL_BUDGET) {
+          this.warn(`[${meta.id}] critical 资源 ${(manifest.criticalBytes / 1e6).toFixed(2)}MB，` + `超过 ${(CRITICAL_BUDGET / 1e6).toFixed(1)}MB 预算，开场会卡`);
+        }
+        if (indexJs) {
+          const inlined = indexJs.code.match(/data:(?:image|audio|video|font)\/[a-z0-9+.-]+;base64,/gi);
+          if (inlined?.length) {
+            this.warn(`[${meta.id}] index.js 里有 ${inlined.length} 个 base64 内联资源——` + `八成是某处 import 漏了 ?no-inline（lib 模式下 assetsInlineLimit 不起作用）`);
+          }
+        }
+      }
+    }
+  };
+}
+
+// dist-npm/vite-config/namespace-css.ts
+import postcss from "postcss";
+function namespaceCss(opts) {
+  const ns = opts.gameId.replace(/[^a-z0-9]+/gi, "-");
+  const scope = opts.scope ?? `.gk-${ns}`;
+  const include = opts.include ?? /\/src\/styles\/[^/]*\.css(\?|$)/;
+  return {
+    name: "gamekit:namespace-css",
+    enforce: "pre",
+    transform(code, id) {
+      if (!include.test(id))
+        return null;
+      const root = postcss.parse(code, { from: id });
+      const renamed = new Set;
+      root.walkAtRules(/^(-\w+-)?keyframes$/, (r) => {
+        renamed.add(r.params);
+        r.params = `${r.params}-${ns}`;
+      });
+      if (renamed.size) {
+        root.walkDecls(/^(-\w+-)?animation(-name)?$/, (d) => {
+          for (const name of renamed) {
+            d.value = d.value.replace(new RegExp(`(^|[\\s,])${escapeRe(name)}(?=$|[\\s,])`, "g"), `$1${name}-${ns}`);
+          }
+        });
+      }
+      root.walkRules((rule) => {
+        const parent = rule.parent;
+        if (parent?.type === "atrule" && /keyframes$/.test(parent.name))
+          return;
+        rule.selectors = rule.selectors.map((sel) => {
+          const s = sel.trim();
+          if (s === ":root" || s === "html" || s === "body")
+            return scope;
+          if (s.startsWith(":root"))
+            return scope + s.slice(":root".length);
+          if (s.startsWith("html") || s.startsWith("body"))
+            return scope + s.slice(4);
+          if (s.startsWith(scope))
+            return s;
+          return `${scope} ${s}`;
+        });
+      });
+      return { code: root.toString(), map: null };
+    }
+  };
+}
+var escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+// dist-npm/vite-config/index.ts
+function defineGameConfig(opts) {
+  const meta = normalizeMeta(opts.meta);
+  const { shareRuntime = false, emitCssFile = false } = opts;
+  const root = opts.root ?? process.cwd();
+  const entry = path.resolve(root, opts.entry ?? "src/index.ts");
+  return defineConfig({
+    root,
+    optimizeDeps: { exclude: ["gamekit777"] },
+    resolve: { dedupe: ["svelte"] },
+    base: "./",
+    plugins: [
+      svelte(),
+      namespaceCss({ gameId: meta.id }),
+      gameManifest({ meta, emitCssFile }),
+      ...opts.plugins ?? []
+    ],
+    build: {
+      target: "es2022",
+      outDir: path.resolve(root, "../../dist/games", meta.id),
+      emptyOutDir: true,
+      sourcemap: false,
+      lib: {
+        entry,
+        formats: ["es"],
+        fileName: () => "index.js",
+        cssFileName: "style"
+      },
+      rollupOptions: {
+        external: shareRuntime ? ["svelte", /^svelte\//] : [],
+        output: {
+          assetFileNames: "assets/[name]-[hash][extname]",
+          chunkFileNames: "chunks/[name]-[hash].js",
+          inlineDynamicImports: true
+        }
+      }
+    }
+  });
+}
+export {
+  defineGameConfig
+};

package/vite-config/index.ts

@@ -0,0 +1,87 @@
+/* 游戏包的构建预设。每个游戏的 vite.config.ts 只需要三行：
+     import { defineGameConfig } from './index.ts';
+     import meta from './game.meta.json' with { type: 'json' };
+     export default defineGameConfig({ meta });
+
+   只产出 index.js 一个入口——视图和逻辑内联在一起。
+   曾经还单独打过一个零 DOM 的 logic.js 给服务端算 payout，但平台改成查表开奖、
+   服务端零执行之后它就没有消费者了：采样在作者机器上跑源码，渲染在客户端。
+   纯度（不碰 DOM、不自取随机）仍然是硬要求，但改由每个游戏 scripts/verify.ts 的
+   运行时桩来保证——那个查的是实际执行路径含全部传递依赖，比对产物 grep 强。 */
+import path from 'node:path';
+import { defineConfig, type PluginOption, type UserConfig } from 'vite';
+import { svelte } from '@sveltejs/vite-plugin-svelte';
+import { normalizeMeta, type GameBuildMetaInput } from './meta.ts';
+import { gameManifest } from './manifest.ts';
+import { namespaceCss } from './namespace-css.ts';
+
+export type { GameBuildMeta, GameBuildMetaInput } from './meta.ts';
+
+export interface GameConfigOptions {
+  meta: GameBuildMetaInput;
+  root?: string;
+  /** 入口，默认 src/index.ts */
+  entry?: string;
+  /**
+   * true = svelte runtime 交给平台的 import map 提供。
+   * 默认 false：每个游戏各带一份约 15KB gzip，换来「文件夹自包含、
+   * 各游戏 Svelte 版本独立升级」。同页要跑二十个小游戏时才值得打开。
+   */
+  shareRuntime?: boolean;
+  /** true = 单独产出 style.css 交给平台加载；默认内联进 index.js */
+  emitCssFile?: boolean;
+  plugins?: PluginOption[];
+}
+
+export function defineGameConfig(opts: GameConfigOptions): UserConfig {
+  const meta = normalizeMeta(opts.meta);
+  const { shareRuntime = false, emitCssFile = false } = opts;
+  const root = opts.root ?? process.cwd();
+  const entry = path.resolve(root, opts.entry ?? 'src/index.ts');
+
+  return defineConfig({
+    root,
+    /* 创作者机器上 gamekit777 是 node_modules 里的真目录，vite 会用 esbuild 预构建它——
+       而 dev-host 的 *.svelte.ts 是 runes 模块，必须过 svelte 插件，esbuild 一碰就炸。
+       仓库内它是 workspace 符号链接，vite 当源码处理，所以这条从没在仓库里暴露过。
+       dedupe 是另一半：预览壳和游戏各自 import 的 svelte 必须是同一份实例，否则 runes 静默失灵 */
+    optimizeDeps: { exclude: ['gamekit777'] },
+    resolve: { dedupe: ['svelte'] },
+    /* 这一行就是 import.meta.url 方案本身：Vite 在 es 格式下会把资源引用编译成
+       new URL('./assets/xxx-hash.jpg', import.meta.url).href，
+       于是游戏文件夹放在任意路径（CDN 子目录）都能正确解析。不要手写 new URL */
+    base: './',
+    plugins: [
+      svelte(),
+      namespaceCss({ gameId: meta.id }),
+      gameManifest({ meta, emitCssFile }),
+      ...(opts.plugins ?? [])
+    ],
+    build: {
+      target: 'es2022',
+      outDir: path.resolve(root, '../../dist/games', meta.id),
+      emptyOutDir: true,
+      sourcemap: false,
+      // cssCodeSplit 不用写：lib 模式会自动关掉
+      lib: {
+        entry,
+        formats: ['es'],
+        fileName: () => 'index.js',
+        cssFileName: 'style'
+      },
+      rollupOptions: {
+        external: shareRuntime ? ['svelte', /^svelte\//] : [],
+        output: {
+          /* 必须覆盖：lib 模式的默认值是 '[name].[ext]'，既没有 hash 也没有子目录 */
+          assetFileNames: 'assets/[name]-[hash][extname]',
+          chunkFileNames: 'chunks/[name]-[hash].js',
+          // 只出一个文件，平台不用管 chunk 路径
+          inlineDynamicImports: true
+        }
+      }
+    },
+    /* 刻意不注入 __GAME_ID__ 之类的全局：那种只在构建下成立的东西
+       会让同一份源码在测试、dev、SSR 里行为不一致。
+       要用元数据就直接 import game.meta.json */
+  });
+}

package/vite-config/manifest.ts

@@ -0,0 +1,144 @@
+/* 构建产物清单。
+
+   为什么要插件而不是只用 import.meta.glob：两者的消费者不同。
+   glob 给游戏自己的 JS 用，它天然拿到带 hash 的正确 URL；
+   manifest.json 给**平台**用——平台要在 import() 游戏之前就知道有哪些资源、
+   多大、什么优先级，才能发 preload 把下载和 JS 解析并行起来。
+
+   插件不扫源码，只读已经产好的 bundle：它看到的就是最终真实产物。 */
+import type { Plugin, Rollup } from 'vite';
+import type { GameBuildMeta } from './meta.ts';
+
+export type AssetType = 'image' | 'audio' | 'font' | 'json' | 'video' | 'binary';
+
+const TYPE_BY_EXT: Record<string, AssetType> = {
+  jpg: 'image', jpeg: 'image', png: 'image', webp: 'image', avif: 'image', svg: 'image', gif: 'image',
+  mp3: 'audio', ogg: 'audio', wav: 'audio', m4a: 'audio',
+  woff: 'font', woff2: 'font', ttf: 'font',
+  json: 'json', mp4: 'video', webm: 'video'
+};
+
+export interface AssetEntry {
+  /** 源码里稳定的名字，如 'critical/coco-classic.jpg' */
+  key: string;
+  /** 产物相对路径，带 hash */
+  path: string;
+  type: AssetType;
+  bytes: number;
+  priority: 'critical' | 'lazy';
+}
+
+export interface GameManifest {
+  id: string;
+  version: string;
+  generatedAt: string;
+  entry: string;
+  /** 独立产出时是文件名；内联进 index.js 时是 null */
+  css: string | null;
+  totalBytes: number;
+  criticalBytes: number;
+  assets: AssetEntry[];
+}
+
+/** critical 资源的预算。超了就告警——批量做游戏时这条比 manifest 本身还有用 */
+const CRITICAL_BUDGET = 1_500_000;
+
+export function gameManifest(opts: { meta: GameBuildMeta; emitCssFile?: boolean }): Plugin {
+  const { meta, emitCssFile = false } = opts;
+
+  return {
+    name: 'gamekit:manifest',
+    /* 必须最后跑。vite 内部的 css-post 插件也是在 generateBundle 里才把 style.css
+       产出来的，早一步就看不见它——CSS 会静静留在 assets/ 下而不是内联进 index.js，
+       而且不会有任何报错 */
+    enforce: 'post',
+    generateBundle: {
+      order: 'post',
+      handler(_o, bundle) {
+        const assets: AssetEntry[] = [];
+
+        for (const file of Object.values(bundle)) {
+          if (file.type !== 'asset') continue;
+          const a = file as Rollup.OutputAsset;
+          if (a.fileName.endsWith('.css')) continue;
+
+          const orig = (a.originalFileName ?? '').replace(/\\/g, '/');
+          const m = /src\/assets\/(critical|lazy)\/(.+)$/.exec(orig);
+          const priority = (m?.[1] ?? 'critical') as 'critical' | 'lazy';
+          const key = m ? `${m[1]}/${m[2]}` : a.fileName;
+
+          const ext = a.fileName.split('.').pop()!.toLowerCase();
+          const src = a.source;
+          assets.push({
+            key, path: a.fileName,
+            type: TYPE_BY_EXT[ext] ?? 'binary',
+            bytes: typeof src === 'string' ? Buffer.byteLength(src) : src.byteLength,
+            priority
+          });
+        }
+
+        assets.sort((x, y) =>
+          x.priority === y.priority ? x.key.localeCompare(y.key) : x.priority === 'critical' ? -1 : 1);
+
+        /* CSS 内联进 index.js 而不是留给平台加载：少一个网络往返、少一个平台必须
+           遵守的约定，也没有「JS 到了 CSS 没到」的闪屏窗口。
+           代价是 CSS 里的 url() 会相对 document 解析而不是相对 CSS 文件——所以要扫一遍 */
+        const cssAsset = Object.values(bundle)
+          .find(f => f.type === 'asset' && f.fileName.endsWith('.css')) as Rollup.OutputAsset | undefined;
+        const indexJs = bundle['index.js'] as Rollup.OutputChunk | undefined;
+        let cssInlined = false;
+
+        if (cssAsset && indexJs && !emitCssFile) {
+          const css = String(cssAsset.source);
+          if (/url\(\s*['"]?(?!data:|#)/.test(css)) {
+            this.warn(`[${meta.id}] CSS 里有 url()，内联注入后会相对 document 解析而错位。`
+                    + `改用 <img> 引用资源，或给 defineGameConfig 传 emitCssFile: true`);
+          }
+          indexJs.code =
+            `(function(){var s=document.createElement('style');`
+            + `s.setAttribute('data-game',${JSON.stringify(meta.id)});`
+            + `s.textContent=${JSON.stringify(css)};`
+            + `document.head.appendChild(s)})();\n` + indexJs.code;
+          delete bundle[cssAsset.fileName];
+          cssInlined = true;
+        }
+
+        const manifest: GameManifest = {
+          id: meta.id,
+          version: meta.version,
+          generatedAt: new Date().toISOString(),
+          entry: 'index.js',
+          css: cssInlined ? null : (cssAsset?.fileName ?? null),
+          totalBytes: assets.reduce((s, a) => s + a.bytes, 0),
+          criticalBytes: assets.filter(a => a.priority === 'critical').reduce((s, a) => s + a.bytes, 0),
+          assets
+        };
+
+        this.emitFile({ type: 'asset', fileName: 'manifest.json', source: JSON.stringify(manifest, null, 2) });
+        this.emitFile({ type: 'asset', fileName: 'meta.json', source: JSON.stringify(meta, null, 2) });
+
+        /* ---- 构建期体检 ---- */
+
+        if (!cssAsset && !emitCssFile) {
+          this.warn(`[${meta.id}] 没找到 CSS 产物。要么游戏真的没样式，`
+                  + `要么这个插件跑得太早（应当 enforce:'post' + order:'post'）`);
+        }
+        if (manifest.criticalBytes > CRITICAL_BUDGET) {
+          this.warn(`[${meta.id}] critical 资源 ${(manifest.criticalBytes / 1e6).toFixed(2)}MB，`
+                  + `超过 ${(CRITICAL_BUDGET / 1e6).toFixed(1)}MB 预算，开场会卡`);
+        }
+        /* lib 模式会无条件把资源 base64 内联进 JS（vite 源码 config.js 的 shouldInline：
+           build.lib 为真时直接 return true，assetsInlineLimit 完全失效），
+           唯一逃生口是给 import 加 ?no-inline。漏掉时构建照样成功，资源只是悄悄
+           胖进 index.js、不在 manifest 里、平台预加载不到——必须把静默失败变成响的 */
+        if (indexJs) {
+          const inlined = indexJs.code.match(/data:(?:image|audio|video|font)\/[a-z0-9+.-]+;base64,/gi);
+          if (inlined?.length) {
+            this.warn(`[${meta.id}] index.js 里有 ${inlined.length} 个 base64 内联资源——`
+                    + `八成是某处 import 漏了 ?no-inline（lib 模式下 assetsInlineLimit 不起作用）`);
+          }
+        }
+      }
+    }
+  };
+}

package/vite-config/meta.ts

@@ -0,0 +1,41 @@
+/** game.meta.json 的形状。它是每个游戏的单一真值源，构建时原样抄进 dist/meta.json */
+export interface GameBuildMeta {
+  id: string;
+  title: string;
+  version: string;
+  /** 舞台建议宽高比，平台排版用 */
+  aspect?: string;
+  orientation?: 'portrait' | 'landscape' | 'any';
+  /** 需要的文档级字体 URL。平台可以提前 preconnect */
+  fonts?: string[];
+}
+
+/** 从 JSON import 进来的原始形状——JSON 的字面量类型会被放宽成 string，
+    所以这里接得松一点，由 normalizeMeta 收窄并校验 */
+export interface GameBuildMetaInput {
+  id: string;
+  title: string;
+  version: string;
+  aspect?: string;
+  orientation?: string;
+  fonts?: string[];
+}
+
+const ORIENTATIONS = ['portrait', 'landscape', 'any'] as const;
+
+/** 校验并收窄。game.meta.json 里写错值会在构建期炸，而不是等平台排版出问题才发现 */
+export function normalizeMeta(m: GameBuildMetaInput): GameBuildMeta {
+  for (const k of ['id', 'title', 'version'] as const) {
+    if (!m[k] || typeof m[k] !== 'string') throw new Error(`game.meta.json 缺少 ${k}`);
+  }
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(m.id)) {
+    throw new Error(`game.meta.json 的 id "${m.id}" 要是小写短横线形式——它同时是输出目录名`);
+  }
+  if (m.orientation !== undefined && !ORIENTATIONS.includes(m.orientation as never)) {
+    throw new Error(`game.meta.json 的 orientation "${m.orientation}" 无效，只能是 ${ORIENTATIONS.join(' / ')}`);
+  }
+  if (m.aspect !== undefined && !/^\d+(\.\d+)?:\d+(\.\d+)?$/.test(m.aspect)) {
+    throw new Error(`game.meta.json 的 aspect "${m.aspect}" 无效，形如 "16:10"`);
+  }
+  return { ...m, orientation: m.orientation as GameBuildMeta['orientation'] };
+}

package/vite-config/namespace-css.ts

@@ -0,0 +1,74 @@
+/* 给游戏的全局 CSS 加命名空间。
+
+   只处理 src/styles/ 下的独立 .css 文件——Svelte 组件的 <style> 已经是
+   scoped 的，编译器还会自动重命名它们内部声明的 @keyframes。
+   逃过重命名的正是这些独立文件里的：coco 的 animations.css 有 14 个
+   @keyframes，名字是 pop / spin / flash / draw / tick / fly / want 这一类。
+
+   @keyframes 是全局命名空间、后定义覆盖先定义，所以同页两个游戏会**静默错乱**：
+   不报错，只是动画播成了别人的。批量做游戏时这几乎必然发生。
+
+   顺带把 :root / html / body 收敛到游戏根元素，否则游戏的页面底色会涂到整个平台上。 */
+import type { Plugin } from 'vite';
+import postcss from 'postcss';
+
+export interface NamespaceCssOptions {
+  gameId: string;
+  /** 命中哪些文件。默认 src/styles/ 下的 .css */
+  include?: RegExp;
+  /** 游戏根元素的 class。默认 gk-<gameId> */
+  scope?: string;
+}
+
+export function namespaceCss(opts: NamespaceCssOptions): Plugin {
+  const ns = opts.gameId.replace(/[^a-z0-9]+/gi, '-');
+  const scope = opts.scope ?? `.gk-${ns}`;
+  const include = opts.include ?? /\/src\/styles\/[^/]*\.css(\?|$)/;
+
+  return {
+    name: 'gamekit:namespace-css',
+    enforce: 'pre',
+    transform(code, id) {
+      if (!include.test(id)) return null;
+
+      const root = postcss.parse(code, { from: id });
+      const renamed = new Set<string>();
+
+      // 1. @keyframes 改名
+      root.walkAtRules(/^(-\w+-)?keyframes$/, r => {
+        renamed.add(r.params);
+        r.params = `${r.params}-${ns}`;
+      });
+
+      // 2. animation / animation-name 里的引用同步改名
+      if (renamed.size) {
+        root.walkDecls(/^(-\w+-)?animation(-name)?$/, d => {
+          for (const name of renamed) {
+            d.value = d.value.replace(
+              new RegExp(`(^|[\\s,])${escapeRe(name)}(?=$|[\\s,])`, 'g'), `$1${name}-${ns}`);
+          }
+        });
+      }
+
+      // 3. 选择器收敛到游戏根元素
+      root.walkRules(rule => {
+        const parent = rule.parent;
+        // @keyframes 里的 0% / from / to 不是选择器，不要动
+        if (parent?.type === 'atrule' && /keyframes$/.test((parent as postcss.AtRule).name)) return;
+
+        rule.selectors = rule.selectors.map(sel => {
+          const s = sel.trim();
+          if (s === ':root' || s === 'html' || s === 'body') return scope;
+          if (s.startsWith(':root')) return scope + s.slice(':root'.length);
+          if (s.startsWith('html') || s.startsWith('body')) return scope + s.slice(4);
+          if (s.startsWith(scope)) return s;               // 已经带了就别叠
+          return `${scope} ${s}`;
+        });
+      });
+
+      return { code: root.toString(), map: null };
+    }
+  };
+}
+
+const escapeRe = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');

package/weights/index.ts

@@ -0,0 +1,11 @@
+export type {
+  Constraint,
+  Group,
+  Problem,
+  Segment,
+  SolveOptions,
+  SolveResult,
+} from './types.ts';
+export { buildConstraints, solve } from './solve.ts';
+export { report, type Report, type SegmentReport } from './report.ts';
+export { pickMedian } from './volatility.ts';

package/weights/linalg.ts

@@ -0,0 +1,118 @@
+/* 只够用的稠密线性代数。矩阵规模是「约束条数」，通常 5~15，
+   所以怎么写都快，优先要的是数值上稳。 */
+
+/** 行主序的 n×n 对称正定矩阵，就地 Cholesky 分解。失败返回 false */
+export function cholesky(a: Float64Array, n: number): boolean {
+  for (let i = 0; i < n; i++) {
+    for (let j = 0; j <= i; j++) {
+      let sum = a[i * n + j]!;
+      for (let k = 0; k < j; k++) sum -= a[i * n + k]! * a[j * n + k]!;
+      if (i === j) {
+        if (!(sum > 0)) return false;
+        a[i * n + i] = Math.sqrt(sum);
+      } else {
+        a[i * n + j] = sum / a[j * n + j]!;
+      }
+    }
+    for (let j = i + 1; j < n; j++) a[i * n + j] = 0;
+  }
+  return true;
+}
+
+/** 用已分解的下三角 L 解 L Lᵀ x = b，就地改写 b */
+export function choleskySolve(l: Float64Array, n: number, b: Float64Array): void {
+  for (let i = 0; i < n; i++) {
+    let sum = b[i]!;
+    for (let k = 0; k < i; k++) sum -= l[i * n + k]! * b[k]!;
+    b[i] = sum / l[i * n + i]!;
+  }
+  for (let i = n - 1; i >= 0; i--) {
+    let sum = b[i]!;
+    for (let k = i + 1; k < n; k++) sum -= l[k * n + i]! * b[k]!;
+    b[i] = sum / l[i * n + i]!;
+  }
+}
+
+/** 解对称正定系统，必要时加岭正则。返回解，或 null 表示怎么加都解不动 */
+export function solveSpd(h: Float64Array, n: number, rhs: Float64Array): Float64Array | null {
+  let scale = 0;
+  for (let i = 0; i < n; i++) scale = Math.max(scale, Math.abs(h[i * n + i]!));
+  if (scale === 0) scale = 1;
+
+  for (let attempt = 0; attempt < 12; attempt++) {
+    const a = Float64Array.from(h);
+    if (attempt > 0) {
+      const ridge = scale * 1e-12 * 10 ** attempt;
+      for (let i = 0; i < n; i++) a[i * n + i] += ridge;
+    }
+    if (!cholesky(a, n)) continue;
+    const x = Float64Array.from(rhs);
+    choleskySolve(a, n, x);
+    let finite = true;
+    for (let i = 0; i < n; i++) if (!Number.isFinite(x[i]!)) finite = false;
+    if (finite) return x;
+  }
+  return null;
+}
+
+export interface RowReduction {
+  /** 保留下来的行下标，彼此线性无关 */
+  keep: number[];
+  /** 与已保留行线性相关、且右端项一致的行 */
+  redundant: number[];
+  /** 与已保留行线性相关、但右端项对不上的行——这意味着约束互斥 */
+  inconsistent: number[];
+}
+
+/**
+ * 对约束矩阵做带主元的 Gram-Schmidt，挑出一组线性无关的行。
+ *
+ * 目的不只是让 Hessian 非奇异：一条「线性相关但右端项对不上」的行，
+ * 恰好就是无解的证据，且能直接指出是哪两条约束在打架。
+ */
+export function reduceRows(
+  rows: readonly Float64Array[],
+  targets: readonly number[],
+  tol = 1e-10,
+): RowReduction {
+  const basis: Float64Array[] = [];
+  const basisTarget: number[] = [];
+  const keep: number[] = [];
+  const redundant: number[] = [];
+  const inconsistent: number[] = [];
+
+  for (let r = 0; r < rows.length; r++) {
+    const v = Float64Array.from(rows[r]!);
+    let t = targets[r]!;
+    let norm0 = 0;
+    for (let i = 0; i < v.length; i++) norm0 += v[i]! * v[i]!;
+    norm0 = Math.sqrt(norm0);
+
+    for (let b = 0; b < basis.length; b++) {
+      const e = basis[b]!;
+      let dot = 0;
+      for (let i = 0; i < v.length; i++) dot += v[i]! * e[i]!;
+      if (dot === 0) continue;
+      for (let i = 0; i < v.length; i++) v[i] -= dot * e[i]!;
+      t -= dot * basisTarget[b]!;
+    }
+
+    let norm = 0;
+    for (let i = 0; i < v.length; i++) norm += v[i]! * v[i]!;
+    norm = Math.sqrt(norm);
+
+    if (norm <= tol * Math.max(1, norm0)) {
+      const slack = Math.abs(t);
+      if (slack <= tol * Math.max(1, Math.abs(targets[r]!))) redundant.push(r);
+      else inconsistent.push(r);
+      continue;
+    }
+
+    for (let i = 0; i < v.length; i++) v[i] /= norm;
+    basis.push(v);
+    basisTarget.push(t / norm);
+    keep.push(r);
+  }
+
+  return { keep, redundant, inconsistent };
+}