第05章 - Vue应用外壳与路由

// apps/site/src/main.ts（全文）
import { createPinia } from 'pinia';
import { createApp } from 'vue';
import App from './App.vue';
import './style.css';
import { initDebug } from './shell/debug';
import { useProgress } from './stores/progress';
import { useSettings } from './stores/settings';

const app = createApp(App);
app.use(createPinia());

// 子组件的 onMounted 先于 App 的 onMounted 执行：深链直达时，
// 语言偏好和调试桥必须在 mount 之前就位，否则首帧按默认中文渲染、e2e 早期读不到桥。
initDebug();
useSettings().init();
void useProgress().init();

app.mount('#app');

// apps/site/src/router.ts（全文）
import { ref } from 'vue';
import type { Ref } from 'vue';
import type { Route } from './shell/routePath';
import { parseRoute } from './shell/routePath';

export type { Route } from './shell/routePath';
export { asLevelId, parseRoute } from './shell/routePath';

const route: Ref<Route> = ref(parseRoute(window.location.hash));

window.addEventListener('hashchange', () => {
  route.value = parseRoute(window.location.hash);
});

export function useRoute(): Ref<Route> {
  return route;
}

export function navigate(path: string): void {
  const next = path.startsWith('#') ? path : '#' + path;
  if (window.location.hash === next) return;
  window.location.hash = next;
}

// apps/site/src/shell/routePath.ts（节选）
export interface Route {
  name: 'home' | 'forge' | 'play' | 'journal' | 'badges' | 'report';
  levelId?: ShippedLevelId;
}

const SHIPPED = new Set<string>(SHIPPED_LEVEL_IDS);

function safeDecode(value: string): string | null {
  try {
    return decodeURIComponent(value);
  } catch {
    return null;
  }
}

/** 只把已发布 id 解析成 player 路由；未发布/不存在的一律回星图（docs/02 §10.1） */
export function asLevelId(value: string | undefined): ShippedLevelId | null {
  if (!value) return null;
  const decoded = safeDecode(value);
  return decoded !== null && SHIPPED.has(decoded) ? (decoded as ShippedLevelId) : null;
}

export function parseRoute(hash: string): Route {
  // `?` 之后是调试参数（autoplay/instant），不参与路由判定
  const clean = hash.split('?')[0] ?? hash;
  const parts = clean.replace(/^#\/?/, '').split('/').filter(Boolean);
  const head = parts[0];
  if (head === 'play') {
    const levelId = asLevelId(parts[1]);
    return levelId ? { name: 'play', levelId } : { name: 'forge' };
  }
  // …forge / journal / badges / report 各一行
  return { name: 'home' };
}

// apps/site/src/registry.ts（节选）
import type { LevelModule, ShippedLevelId } from '@mmf/game-kit';

export type LevelLoader = () => Promise<{ default: LevelModule }>;

/** 只登记已发布关卡；Record 少一条 typecheck 就报 */
export const registry: Record<ShippedLevelId, LevelLoader> = {
  'k-structure-pattern-path': () => import('@mmf/game-forge/k-structure-pattern-path'),
  'k-data-tally': () => import('@mmf/game-forge/k-data-tally'),
  // …共 20 条，与 SHIPPED_LEVEL_IDS 一一对应
};

// games/forge/src/index.ts（节选注释）
 * 这里刻意不 re-export 任何关卡模块：一句 export * from './levels/...'
 * 就会让所有关卡（连同 Phaser 画布场景）进入同一个 chunk。
export {};

// apps/site/vite.config.ts（节选）
chunkFileNames(chunk) {
  const id = chunk.facadeModuleId ?? '';
  const level = /[\\/]games[\\/]forge[\\/]src[\\/]levels[\\/]([^\\/]+)\.ts$/.exec(id);
  if (level) return 'assets/level-' + level[1] + '-[hash].js';
  const detail = /[\\/]content[\\/]src[\\/]details[\\/]([^\\/]+)\.level\.json$/.exec(id);
  if (detail) return 'assets/content-' + detail[1] + '-[hash].js';
  if (chunk.name.includes('phaser')) return 'assets/vendor-phaser-[hash].js';
  return 'assets/[name]-[hash].js';
}

// apps/site/src/views/ForgeView.vue（节选）
const view = ref<'band' | 'thread'>('band');

const sections = computed<StarSection[]>(() => {
  if (view.value === 'thread') {
    return THREADS.map((thread) => {
      const levels = threadLevels(progress.save, locale.value, thread);
      return {
        key: thread, emoji: THREAD_EMOJI[thread], label: t('thread.' + thread), levels,
        completedCount: levels.filter((node) => node.completed).length,
      };
    }).filter((section) => section.levels.length > 0);
  }
  return bandGroups(progress.save, locale.value).map((group) => ({
    key: group.band, emoji: BAND_EMOJI[group.band], label: t('band.' + group.band),
    levels: group.levels, completedCount: group.completedCount,
  })).filter((section) => section.levels.length > 0);
});

// apps/site/src/stores/progress.ts（节选）
export const useProgress = defineStore('progress', () => {
  // 存档与证据是整棵替换的快照，不能放进深层 reactive（docs/02 §19-10）：
  // 每次 sync 都会换新对象，shallowRef 就足够触发视图更新。
  const save = shallowRef<SaveData | null>(null);
  const ready = shallowRef(false);
  const evidence = shallowRef<EvidenceEvent[]>([]);
  const initError = shallowRef<string | null>(null);
  let inflight: Promise<void> | null = null;

  function sync(): void {
    const snapshot = progressManager.snapshot();
    save.value = snapshot;
    setDebugSave(snapshot);
  }

  function init(): Promise<void> {
    inflight ??= (async () => { /* 读档；失败记 initError 并从空档开始 */ })();
    return inflight;
  }
  // completeLevel / recordEvidence / loadEvidence / refreshBadges / completedBefore / clear …
});

// apps/site/src/stores/settings.ts（节选）
async function setLocalePreference(next: Locale): Promise<void> {
  if (next === locale.value) return;
  try {
    // 补丁没就位就切状态，会出现"界面英文、卡片中文"；失败保持当前语言（回落中文）。
    await ensureMessages(next);
  } catch (cause) {
    console.warn('[mmf] 语言补丁加载失败，保持当前语言', cause);
    return;
  }
  platform.preferences.set('locale', next);
  setLocale(next);
}

// apps/site/src/shell/locale.ts（全文）
export const locale = ref<Locale>('zh-CN');

export function setLocale(next: Locale): void {
  locale.value = next;
  setTranslatorLocale(next);
}

// apps/site/src/shell/debug.ts（节选）
const MAX_DEBUG_EVENTS = 400;

export interface MmfDebugBridge {
  events: string[];
  save: SaveData | null;
  snapshot: RunSnapshot | null;
  lastError?: string;
  attemptSubmit?: () => Promise<void>;
}

/** 调试桥只在 DEV / webdriver 暴露；生产分享链接拿不到它（docs/02 §10.5） */
export function debugAllowed(): boolean {
  if (import.meta.env.DEV) return true;
  return typeof navigator !== 'undefined' && navigator.webdriver === true;
}

// apps/site/src/shell/createLevelContext.ts（节选）
export function readDebugOptions(): DebugOptions | undefined {
  if (!(import.meta.env.DEV || (typeof navigator !== 'undefined' && navigator.webdriver === true))) {
    return undefined;
  }
  const params = new URLSearchParams(window.location.search);
  const hash = window.location.hash;
  const queryAt = hash.indexOf('?');
  if (queryAt >= 0) {
    // 把 hash 内 ? 之后的调试参数并进 params（hash 路由下 location.search 读不到它们）
    for (const [key, value] of new URLSearchParams(hash.slice(queryAt + 1))) {
      if (!params.has(key)) params.set(key, value);
    }
  }
  const autoplay = params.get('autoplay') === '1';
  const instant = params.get('instant') === '1';
  if (!autoplay && !instant) return undefined;
  // …返回 { autoplay?, instant? }
}

// apps/site/src/views/WorkshopView.vue（节选）
if (debugOptions?.autoplay) {
  const result = await runtimeRef.autoplay();
  await flushEvidence();
  finalSnapshot.value = result.snapshot;
  liveSnapshot.value = result.snapshot;
  verdictUsageAt.value = usageTotal(result.snapshot);
  setDebugSnapshot(result.snapshot);
  if (result.verdict?.passed) await completeNow(result.verdict.stamps, result.snapshot.variantId);
}

// apps/site/src/shell/seed.ts（全文）
/**
 * 关卡种子：同一档案进同一关应得到同一序列（docs/02 §10.3 的 seedFor）。
 * 用 FNV-1a 而不是 Math.random：重进关卡内容不漂移，问题也可复现。
 */
export function seedFor(levelId: string, profileId: string): number {
  const input = levelId + '|' + profileId;
  let hash = 2166136261;
  for (let index = 0; index < input.length; index += 1) {
    hash ^= input.charCodeAt(index);
    hash = Math.imul(hash, 16777619);
  }
  return (hash >>> 0) % 1_000_000_000;
}

// apps/site/src/views/WorkshopView.vue（节选）
async function teardown(): Promise<void> {
  clearExitTimer();
  offPause?.();
  offResume?.();
  offPause = null;
  offResume = null;
  unsubscribe?.();
  unsubscribe = null;
  registerSubmit(null);
  setDebugSnapshot(null);
  const active = module.value;
  module.value = null;
  runtime.value = null;
  liveSnapshot.value = null;
  if (active) {
    try {
      await active.unmount();
    } catch (cause) {
      recordDebugError('关卡卸载失败：' + String(cause));
    }
  }
  safeRemove(canvasHost.value);
  safeRemove(host.value);
}

onBeforeUnmount(() => {
  // 不写成 async：Vue 不会等异步钩子，等 await 期间新页面可能已经挂载同一关卡的模块单例，
  // 那时再 unmount 会把新画布销毁。同步拆干净，证据落盘单独发起。
  disposed = true;
  platform.audio.stopSpeech();
  void teardown();
  void flushEvidence();
});