@realsee/vr-cli 0.1.3

package/skills/realsee-vr-app/scripts/verify-project.mjs

@@ -0,0 +1,1566 @@
+#!/usr/bin/env node
+
+import { execFile } from 'node:child_process'
+import { readFile, readdir, stat } from 'node:fs/promises'
+import path from 'node:path'
+import { promisify } from 'node:util'
+
+const execFileAsync = promisify(execFile)
+
+const root = path.resolve(process.argv[2] || process.cwd())
+const nodeVersion = '22.23.2'
+const minimumNodeVersion = '22.18.0'
+const nodeEngine = '>=22.18.0'
+const npmVersion = '11.19.0'
+const npmEngine = '>=11.19.0'
+const packageManager = 'npm@11.19.0'
+const expected = {
+  '@fastify/static': '10.1.3',
+  '@realsee/dnalogel': '3.81.2',
+  '@realsee/five': '6.8.9',
+  '@realsee/vapor': '0.2.12',
+  fastify: '5.12.1',
+  react: '18.3.1',
+  'react-dom': '18.3.1',
+  three: '0.117.1',
+}
+const expectedDev = {
+  '@eslint/js': '10.0.1',
+  '@types/node': '24.13.3',
+  '@types/react': '18.3.12',
+  '@types/react-dom': '18.3.1',
+  '@vitejs/plugin-react': '4.3.1',
+  concurrently: '10.0.5',
+  eslint: '10.9.1',
+  'eslint-plugin-react-hooks': '7.1.1',
+  globals: '17.11.0',
+  prettier: '3.9.6',
+  typescript: '5.9.3',
+  'typescript-eslint': '8.68.0',
+  vite: '5.4.14',
+}
+const requiredEnvKeys = [
+  'APP_ID',
+  'REALSEE_GATEWAY_ENDPOINT',
+  'REALSEE_GATEWAY_APP_KEY',
+  'REALSEE_GATEWAY_APP_SECRET',
+  'REALSEE_SOURCE',
+]
+const credentialEnvKeys = [
+  'REALSEE_GATEWAY_APP_KEY',
+  'REALSEE_GATEWAY_APP_SECRET',
+]
+const secretEnvKeys = ['REALSEE_GATEWAY_APP_SECRET']
+const requiredFiles = [
+  'package.json',
+  'package-lock.json',
+  'README.md',
+  'index.html',
+  'tsconfig.json',
+  'tsconfig.server.json',
+  'vite.config.ts',
+  '.editorconfig',
+  '.nvmrc',
+  '.node-version',
+  '.npmrc',
+  '.prettierignore',
+  '.vr-cli.json',
+  'eslint.config.mjs',
+  'prettier.config.mjs',
+  'server/types.ts',
+  'server/config.ts',
+  'server/check-config.ts',
+  'server/realsee-open-api.ts',
+  'server/work-service.ts',
+  'server/work-route.ts',
+  'server/app.ts',
+  'server/index.ts',
+  'shared/model-floorplan.ts',
+  'src/main.tsx',
+  'src/app/App.tsx',
+  'src/shared/useElementSize.ts',
+  'src/vr/five/api.ts',
+  'src/vr/five/fiveConfig.ts',
+  'src/vr/five/SpatialRuntimeProvider.tsx',
+  'src/vr/five/initialState.ts',
+  'src/vr/plugins/dnalogel.ts',
+  'src/vr/plugins/SpatialPluginRegistry.ts',
+  'src/vr/plugins/examples/FeatureOwnedMeshPlugin.ts',
+  'src/vr/work/WorkSource.ts',
+  'src/features/floorplan/ModelFloorplanFeature.ts',
+  'src/features/navigation/ModeSwitcher.tsx',
+  'src/features/tags/PanoTagFeature.ts',
+  'src/ui/ViewerOverlay.tsx',
+  'src/styles.css',
+  'AGENTS.md',
+  '.agents/skills/realsee-vr-app/SKILL.md',
+  '.agents/skills/realsee-vr-app/references/dnalogel-api-capabilities.md',
+  '.agents/skills/realsee-vr-app/references/five-api-capabilities.md',
+  '.agents/skills/realsee-vr-app/references/five-runtime.md',
+  '.agents/skills/realsee-vr-app/references/official-docs.md',
+  '.agents/skills/realsee-vr-app/references/plugin-lifecycle.md',
+  '.agents/skills/realsee-vr-app/references/ui-and-validation.md',
+  '.agents/skills/realsee-vr-app/references/vapor-dom-layer.md',
+  '.agents/skills/realsee-vr-app/scripts/verify-project.mjs',
+  '.agents/skills/realsee-image-resources/SKILL.md',
+  '.agents/skills/realsee-image-resources/references/cors-and-three-textures.md',
+  '.agents/skills/realsee-image-resources/references/data-wanxiang.md',
+  '.agents/skills/realsee-image-resources/references/five-image-url-transform.md',
+  '.agents/skills/realsee-image-resources/references/source-and-domain-policy.md',
+  '.agents/skills/threejs-r117-five/SKILL.md',
+  '.agents/skills/threejs-r117-five/references/r117-capabilities.md',
+  '.agents/skills/threejs-r117-five/references/r117-version-guards.md',
+  '.agents/skills/threejs-r117-five/references/five-ownership.md',
+  '.env.example',
+  '.gitignore',
+]
+const fiveEntryPoints = [
+  '@realsee/five',
+  '@realsee/five/plugins',
+  '@realsee/five/line',
+  '@realsee/five/sticker',
+  '@realsee/five/vfx',
+  '@realsee/five/gltf-loader',
+  '@realsee/five/shader-lib',
+  '@realsee/five/work-downloader',
+]
+// Three is the only hard-locked dependency: Five 6.8.9 targets r117.
+// Every other dependency uses an open minimum range so it can move to any newer release.
+const lockedDependencies = { three: expected.three }
+const dependencySpec = (name, version) =>
+  name in lockedDependencies ? version : `>=${version}`
+const specMinimumVersion = (spec) => {
+  if (typeof spec !== 'string') return null
+  const match = /^>=(\d+\.\d+\.\d+(?:[-+][\w.]+)?)$/.exec(spec.trim())
+  return match ? match[1] : null
+}
+const failures = []
+const warnings = []
+const isSensitiveKey = (key) =>
+  /(?:^|_)(?:AK|SK|SECRET|TOKEN|PASSWORD|CREDENTIALS?)(?:_|$)/i.test(key)
+// Target the actual server-only configuration keys. A blanket `REALSEE_[A-Z0-9_]+`
+// also matched harmless browser constants such as the documented
+// `REALSEE_IMAGE_URL_MAPPINGS`, which the image-resource guidance itself recommends.
+const serverOnlyBrowserPatterns = [
+  /\bAPP_ID\b/,
+  /\bREALSEE_(?:GATEWAY_[A-Z0-9_]+|SOURCE|ACCESS_TOKEN)\b/,
+  /\b(?:VITE_)?(?:AK|SK|ACCESS_TOKEN)\b/,
+]
+const findServerOnlyBrowserMarker = (source) => {
+  for (const pattern of serverOnlyBrowserPatterns) {
+    const match = pattern.exec(source)
+    if (match) return match[0]
+  }
+  return null
+}
+const stripSourceComments = (source) =>
+  source.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/.*$/gm, '$1')
+// Representative high-signal regressions only; declarations, typecheck, build and browser validation remain authoritative.
+const threeR117Regressions = [
+  [/three\/addons\//, 'r117 extensions must import from three/examples/jsm'],
+  [/three\/tsl\b/, 'Three r117 does not provide the modern TSL entry'],
+  [
+    /\b(?:SRGBColorSpace|LinearSRGBColorSpace|NoColorSpace|CapsuleGeometry|WebGPURenderer)\b/,
+    'source uses a symbol unavailable in Three r117',
+  ],
+  [
+    /\b(?:renderer|[\w$]*Renderer)\.outputColorSpace\b/,
+    'Three r117 uses renderer.outputEncoding',
+  ],
+  [
+    /\b(?:texture|[\w$]*(?:map|Map|texture|Texture))\.colorSpace\s*=/,
+    'Three r117 textures use encoding instead of colorSpace',
+  ],
+]
+const customPluginRequiredMarkers = [
+  "from '@realsee/five'",
+  "from 'three'",
+  'FEATURE_OWNED_MESH_PLUGIN_NAME',
+  'example.featureOwnedMesh',
+  'new Group(',
+  'new BoxBufferGeometry(',
+  'new MeshBasicMaterial(',
+  'new Mesh(',
+  'five.scene.add(root)',
+  'root.parent?.remove(root)',
+  'five.needsRender = true',
+  'geometry.dispose()',
+  'material.dispose()',
+  'plugins.register(FEATURE_OWNED_MESH_PLUGIN_NAME, plugin)',
+  'plugin.dispose()',
+]
+const customPluginForbiddenMarkers = [
+  'new Five(',
+  'new WebGLRenderer(',
+  'renderer.render(',
+  'requestAnimationFrame(',
+  'five.dispose(',
+  'three/addons/',
+]
+const imageResourceGuidanceMarkers = [
+  'Image resources use approved Realsee CDN domains only; never use `ljcdn.com`, `lianjia.com` or their subdomains.',
+  'Prefer Five `defaultImageURLTransform` over hand-built 数据万象 query strings when its installed contract satisfies the request.',
+  'URL transformation does not grant CORS access.',
+  "Ordinary images use the deployment's approved image-4 host.",
+  'Feature media from OpenAPI or Work data is displayed through a derived sized variant, never the original: pass ordinary images through the reviewed `defaultImageURLTransform` adapter with a bounded `size`, and do not hand a full-resolution URL to a tag, tour, card or DOM thumbnail.',
+]
+const vaporGuidanceMarkers = [
+  'When the user explicitly requests Vapor components, use matching named exports from the installed `@realsee/vapor` package for every applicable DOM control; importing `Vapor` or `vapor.css` alone does not satisfy the request.',
+  'Do not replace an available Vapor component with raw HTML or a locally styled replica; use raw DOM only for semantics or capabilities absent from the installed Vapor declarations, and record that gap.',
+  'Before implementing Vapor UI, read `node_modules/@realsee/vapor/AI_CONTEXT.md`, `llms.txt`, `vapor.d.ts`, and the selected component declarations; never invent component names or props.',
+  "Use the installed `ai_guides` only for component discovery and composition recipes; the target project's root `vapor.d.ts` and selected component declarations are the API contract, and conflicts resolve in favor of installed declarations.",
+  'Keep the Five canvas in its dedicated sibling host outside `Vapor`; Vapor layout components own DOM chrome only, even when an external recipe nests a placeholder VR component inside a stack.',
+]
+const vaporReferenceMarkers = [
+  'The current generated baseline is `@realsee/vapor@0.2.12`.',
+  'The 0.2.12 baseline requires exactly one executable `@realsee/vapor/vapor.css` import, not `vapor.scss`',
+  'Choose by product semantics before styling:',
+  '`HStack` arranges DOM horizontally, `VStack` vertically and `ZStack` overlays DOM children.',
+  'The 0.2.12 match union is exact:',
+  'if both represent the same physical inset, de-duplicate rather than adding it twice.',
+]
+const vaporAcceptanceMarkers = [
+  'For an explicit Vapor request, executable source must import and render the matching non-provider Vapor component; the provider and stylesheet alone are insufficient.',
+  'exactly one executable `@realsee/vapor/vapor.css` import and no `vapor.scss` or copied internal stylesheet;',
+  'the `Vapor` provider rectangle matches the DOM overlay host',
+  'safe-area behavior uses the declared source/merge rule without double-counting',
+  'correct portal order, focus entry/return, Escape/backdrop behavior and close reasons;',
+  'no application stylesheet overrides `.vapor-*` internals',
+  'typecheck validates every component prop, compound child and symbol',
+]
+const vaporCssImportPattern =
+  /\bimport\s*['"]@realsee\/vapor\/vapor\.css['"]\s*;?/
+const countVaporCssImports = (source) =>
+  source.match(new RegExp(vaporCssImportPattern.source, 'g'))?.length ?? 0
+const hasVaporNamedImport = (source, symbol) =>
+  new RegExp(
+    `\\bimport\\s*\\{[^}]*\\b${symbol}\\b[^}]*\\}\\s*from\\s*['"]@realsee/vapor['"]`,
+  ).test(source)
+const hasJsxElement = (source, symbol) =>
+  new RegExp(`<${symbol}(?:\\s|/?>)`).test(source)
+const spatialTagGuidanceMarkers = [
+  'Spatial capability resolution order: installed @realsee/dnalogel preset -> native Five -> Three.js.',
+  'Tags, hotspots, and anchors default to PanoTagPlugin with GET /open/v3/hot/list.',
+  'Normalize optional OpenAPI configuration fields such as `version`, `globalConfig` and `contentTypeConfig`: treat `null` as absent before validating the installed SDK contract.',
+  'Load ordinary PanoTag point/plane tags after `five.load` without waiting for `five.model.loaded`; gate only model-dependent tag content or anchors on model readiness.',
+  'Tours use Five State snapshots with GET /open/v3/observerpicture/search.',
+  'Model annotations default to ModelMakerPlugin with GET /open/v3/annotation/search.',
+  'Routes use GuideLinePlugin for rendering and shape-selected CruisePlugin or MovePlugin playback with GET /open/v3/route/search.',
+  'Tour adapters read `data.list`, map each validated record to `Partial<State>` with the active `workCode`, and never cast an observer-picture record directly to `State`.',
+  'Model annotation adapters read `data.list`, validate `object_data` for `box`, `triangles` or `prism`, and pass `{ list }` to ModelMaker only for a model-capable Work.',
+  'Feature API, schema, or plugin failures disable only the affected feature; keep the base Viewer usable and never runtime-fallback to raw data or a custom Three implementation.',
+  'Scope tour, ModelMaker, GuideLine, Cruise and Move work to an active `workCode`/generation token; abort fetches, ignore stale continuations, pause the owned playback controller, remove hooks, clear GuideLine data, wait for pending loads, then let identity-safe unregister dispose each registered controller exactly once before `five.dispose()`.',
+  'SDK-shaped custom data requires an explicit developer opt-out from Open Platform data.',
+  'VR spatial tag (spatial annotation) is the umbrella concept',
+  'Classify content, renderer, anchor, and lifecycle/data ownership',
+  'Never infer PanoTag from',
+  'Never directly edit `work.json`, downloaded Work, or customer Work',
+]
+const routeGuidanceMarkers = [
+  'dnalogel 3.81.2 route playback is shape-selected: a validated pano group uses `CruisePlugin` `{ panoIndexList }`, while a validated model-space curve uses `MovePlugin` `{ path }`; `GuideLinePlugin` renders route geometry and is not playback input.',
+  '`CruisePlugin` accepts exactly one of `panoIndexList` or `keyframes`; its installed union has no type discriminator.',
+  'OpenAPI route records are never passed raw: rename validated style config only for GuideLine `lines`, and never pass GuideLine `PathItem` arrays or style objects to `CruisePlugin` or `MovePlugin`.',
+  'If a source record contains both `pano_group` and `path`, the route adapter must choose product semantics explicitly and pass only the selected geometry branch to GuideLine.',
+  '`GuideLinePlugin.load` waits for model readiness; `CruisePlugin` waits only for Work and observers; `MovePlugin` enters Model and awaits Five readiness when playback starts.',
+  'Reject empty routes, unknown pano indexes, unsupported curves, non-finite coordinates, timing or speed, and ambiguous multi-segment Move paths before plugin load.',
+  'Route cleanup pauses the owned playback controller before hook removal and disposal; `clear` belongs to GuideLine, is not a public Cruise operation, and GuideLine disposal does not own an external or embedded Cruise controller automatically.',
+  'Do not invent `RoutePlugin`, `PanoRove`, `stop()`, or a universal route controller; use only the exports and methods declared by the installed package.',
+]
+const floorplanGuidanceMarkers = [
+  'Floorplans default to ModelFloorplanPlugin with GET /open/v3/floorplan/plugins.',
+  '`data.format_floorplan_url`, not `format_model_url`, resolves to the preferred `{ version, data: FloorplanServerData }` plugin input.',
+  'Expose `capabilities.modelFloorplan` only after validating the complete wrapper and nested floorplan shape; missing, empty, malformed or failed floorplan data must leave the base Viewer usable.',
+  'The default tabs are `漫游` for `Panorama` and `三维模型` for `Mapview`; do not expose `Topview` as `地图`.',
+  'Add the `平面图` tab only after the capability validates and `ModelFloorplanPlugin.load` succeeds.',
+  'Configure `ModelFloorplanPlugin` with `autoShowEnable: false`; the application tab owns explicit `show()`/`hide()`, uses `modelOpacity: 0` while the floorplan is visible, and restores the Five model surface on hide, failure, and disposal.',
+  'Resolve the Five canvas parent and call `ModelFloorplanPlugin.appendTo(wrapper)` before `load`; `five.addExtraElement` registers input handling but does not mount the plugin DOM.',
+  'For multi-floor Work, ModelFloorplanPlugin and Five pano/model floor synchronization are the floor source of truth; do not invent a React-only `floorIndex`.',
+  'Floorplan show/hide, hooks, pending load and identity-safe disposal must finish before `five.dispose()`.',
+]
+// One authoritative contract; always-on files keep the routing summary and the other
+// references link to it instead of restating nine rules apiece.
+const floorplanSummaryMarkers = floorplanGuidanceMarkers.slice(0, 3)
+const floorplanPointerMarker = 'The complete model floorplan contract lives in'
+const routePointerMarker = 'The complete route playback contract lives in'
+const routeSummaryMarkers = [
+  routeGuidanceMarkers[0],
+  routeGuidanceMarkers[7],
+  routePointerMarker,
+]
+
+const viewerOverlayComponents = [
+  'Vapor',
+  'Text',
+  'TitleBar',
+  'ZStack',
+  'VStack',
+  'Layer',
+]
+const viewerModeSwitcherComponents = ['Button', 'Font', 'HStack', 'VStack']
+// Project invariants only. `VaporConfig` defaults width/height to 100vw/100vh, so a
+// provider inside the sized overlay host must override both; the status region must
+// stay an accessible live region; safe-area insets must reach CSS. Exact copy, class
+// names, spacing and decorative props are generator template fidelity instead.
+const viewerOverlayInvariantMarkers = [
+  'width="100%"',
+  'height="100%"',
+  'useSaveAreaInsets()',
+  'useDimension()',
+  "role={error ? 'alert' : 'status'}",
+  "aria-live={error ? 'assertive' : 'polite'}",
+  'env(safe-area-inset-${side}, 0px)',
+]
+// Project invariants only: an accessible group and declaration-driven responsive
+// branching. Exact sizes, weights and class names belong to generator template
+// fidelity and are asserted by the generator's own check, not in a user project.
+const viewerModeSwitcherAccessibilityMarkers = [
+  'role="group"',
+  'useDimension()',
+]
+const viewerForbiddenOverlayMarkers = [
+  'viewer-glass',
+  'className="viewer-topbar"',
+  '<h1',
+]
+const viewerForbiddenModeSwitcherMarkers = [
+  'Segmented',
+  'viewer-segmented',
+  'viewer-glass',
+  'appearance="horizontal"',
+  'maxWidth="100%"',
+]
+const viewerForbiddenStyleMarkers = [
+  '--viewer-glass-',
+  '--viewer-control-size',
+  '.vapor-segmented',
+  'backdrop-filter',
+]
+
+function versionAtLeast(actual, required) {
+  const parse = (version) => {
+    if (typeof version !== 'string') return null
+    const match =
+      /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(
+        version.trim(),
+      )
+    return match
+      ? {
+          core: match.slice(1, 4).map(Number),
+          prerelease: match[4] ?? null,
+        }
+      : null
+  }
+  const actualVersion = parse(actual)
+  const requiredVersion = parse(required)
+  if (!actualVersion || !requiredVersion) return false
+  for (let index = 0; index < 3; index += 1) {
+    const difference = actualVersion.core[index] - requiredVersion.core[index]
+    if (difference > 0) return true
+    if (difference < 0) return false
+  }
+  if (actualVersion.prerelease === requiredVersion.prerelease) return true
+  if (actualVersion.prerelease === null) return true
+  if (requiredVersion.prerelease === null) return false
+  return actualVersion.prerelease.localeCompare(requiredVersion.prerelease, 'en', {
+    numeric: true,
+  }) >= 0
+}
+
+async function currentNpmVersion() {
+  const command = process.platform === 'win32' ? 'npm.cmd' : 'npm'
+  const { stdout } = await execFileAsync(command, ['--version'], {
+    encoding: 'utf8',
+  })
+  return stdout.trim()
+}
+
+async function exists(file) {
+  try {
+    await stat(path.join(root, file))
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function collectSourceFiles(directory) {
+  const files = []
+  if (!(await exists(directory))) return files
+  for (const entry of await readdir(path.join(root, directory), {
+    withFileTypes: true,
+  })) {
+    const relative = path.join(directory, entry.name)
+    if (entry.isDirectory()) files.push(...(await collectSourceFiles(relative)))
+    else if (entry.isFile() && /\.(?:[cm]?[jt]sx?)$/.test(entry.name))
+      files.push(relative)
+  }
+  return files
+}
+
+function parseEnv(content) {
+  const values = new Map()
+  for (const line of content.split(/\r?\n/)) {
+    const trimmed = line.trim()
+    if (!trimmed || trimmed.startsWith('#')) continue
+    const match = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/.exec(trimmed)
+    if (match) values.set(match[1], match[2].trim())
+  }
+  return values
+}
+
+if (!versionAtLeast(process.versions.node, minimumNodeVersion)) {
+  failures.push(
+    `Node must be >=${minimumNodeVersion}; current ${process.versions.node}`,
+  )
+}
+try {
+  const actualNpmVersion = await currentNpmVersion()
+  if (!versionAtLeast(actualNpmVersion, npmVersion)) {
+    failures.push(`npm must be >=${npmVersion}; current ${actualNpmVersion}`)
+  }
+} catch (error) {
+  failures.push(`npm --version failed: ${String(error)}`)
+}
+
+try {
+  const pkg = JSON.parse(
+    await readFile(path.join(root, 'package.json'), 'utf8'),
+  )
+  if (pkg.private !== true) failures.push('package.json private must be true')
+  if (pkg.type !== 'module')
+    failures.push('package.json type must equal module')
+  if (pkg.packageManager !== packageManager)
+    failures.push(`packageManager must equal ${packageManager}`)
+  if (pkg.engines?.node !== nodeEngine)
+    failures.push(`engines.node must equal ${nodeEngine}`)
+  if (pkg.engines?.npm !== npmEngine)
+    failures.push(`engines.npm must equal ${npmEngine}`)
+  for (const [declared, baseline] of [
+    [pkg.dependencies, expected],
+    [pkg.devDependencies, expectedDev],
+  ]) {
+    for (const [name, version] of Object.entries(baseline)) {
+      const actual = declared?.[name]
+      if (actual === undefined) {
+        failures.push(
+          `${name} must be declared; generator baseline is ${version}`,
+        )
+        continue
+      }
+      if (name in lockedDependencies) {
+        if (actual !== version) {
+          failures.push(
+            `${name} must stay locked at ${version} because Five 6.8.9 targets that Three release; found ${actual}`,
+          )
+        }
+        continue
+      }
+      const minimum = specMinimumVersion(actual)
+      if (!minimum) {
+        failures.push(
+          `${name} must use an open minimum range >=x.y.z; generator baseline is >=${version}, found ${actual}`,
+        )
+        continue
+      }
+      if (!versionAtLeast(minimum, version)) {
+        failures.push(
+          `${name} declares minimum ${minimum}, below generator baseline ${version}`,
+        )
+        continue
+      }
+      if (actual !== dependencySpec(name, version)) {
+        warnings.push(
+          `${name} raised its minimum from generator baseline ${version} to ${minimum}; re-run npm run check and npm run build, and re-verify versioned fixtures for SDK upgrades`,
+        )
+      }
+    }
+  }
+  for (const [name, markers] of [
+    ['dev', ['check:env', 'concurrently']],
+    ['dev:bff', ['--env-file-if-exists=.env.development', 'server/index.ts']],
+    ['dev:web', ['vite']],
+    [
+      'check:env',
+      ['--env-file-if-exists=.env.development', 'server/check-config.ts'],
+    ],
+    ['typecheck', ['npm run typecheck:web', 'npm run typecheck:bff']],
+    ['typecheck:web', ['tsc -p tsconfig.json']],
+    ['typecheck:bff', ['tsc -p tsconfig.server.json']],
+    ['lint', ['eslint . --max-warnings=0']],
+    ['format', ['prettier --write .']],
+    ['format:check', ['prettier --check .']],
+    ['check', ['npm run typecheck', 'npm run lint', 'npm run format:check']],
+    ['check:bff', ['typecheck:bff']],
+    ['deps:relock', ['npm install --package-lock-only']],
+    ['deps:install', ['npm ci']],
+    [
+      'start',
+      [
+        '--env-file-if-exists=.env.development',
+        'server/index.ts',
+        '--serve-frontend',
+      ],
+    ],
+  ]) {
+    for (const marker of markers) {
+      if (!pkg.scripts?.[name]?.includes(marker))
+        failures.push(`scripts.${name} must include ${marker}`)
+    }
+  }
+  if (await exists('package-lock.json')) {
+    const lockfile = JSON.parse(
+      await readFile(path.join(root, 'package-lock.json'), 'utf8'),
+    )
+    const lockRoot = lockfile.packages?.['']
+    if (lockfile.lockfileVersion !== 3 || !lockRoot)
+      failures.push(
+        'package-lock.json must use lockfileVersion 3 with a root package',
+      )
+    else {
+      if (
+        lockfile.name !== pkg.name ||
+        lockRoot.name !== pkg.name ||
+        lockRoot.version !== pkg.version
+      ) {
+        failures.push(
+          'package-lock.json root name/version must match package.json',
+        )
+      }
+      for (const [lockDeclared, declared, baseline, label] of [
+        [
+          lockRoot.dependencies,
+          pkg.dependencies,
+          expected,
+          'dependencies',
+        ],
+        [
+          lockRoot.devDependencies,
+          pkg.devDependencies,
+          expectedDev,
+          'devDependencies',
+        ],
+      ]) {
+        for (const [name, declaredSpec] of Object.entries(declared ?? {})) {
+          if (lockDeclared?.[name] !== declaredSpec) {
+            failures.push(
+              `package-lock.json ${label} must match package.json for ${name}@${declaredSpec}; run npm run deps:relock`,
+            )
+          }
+          const baselineVersion = baseline[name]
+          if (!baselineVersion) continue
+          const resolvedVersion =
+            lockfile.packages?.[`node_modules/${name}`]?.version
+          if (!resolvedVersion) {
+            failures.push(
+              `package-lock.json must contain a resolved direct version for ${name}`,
+            )
+            continue
+          }
+          if (name in lockedDependencies) {
+            if (resolvedVersion !== baselineVersion) {
+              failures.push(
+                `package-lock.json must resolve ${name} to ${baselineVersion}; found ${resolvedVersion}`,
+              )
+            }
+            continue
+          }
+          const declaredMinimum = specMinimumVersion(declaredSpec)
+          if (
+            declaredMinimum &&
+            (!versionAtLeast(resolvedVersion, baselineVersion) ||
+              !versionAtLeast(resolvedVersion, declaredMinimum))
+          ) {
+            failures.push(
+              `package-lock.json resolves ${name} to ${resolvedVersion}; it must satisfy generator baseline >=${baselineVersion} and declaration ${declaredSpec}`,
+            )
+          }
+        }
+      }
+    }
+  }
+} catch (error) {
+  failures.push(`package metadata: ${String(error)}`)
+}
+
+for (const file of requiredFiles) {
+  if (!(await exists(file))) failures.push(`missing ${file}`)
+}
+
+if ((await exists('.vr-cli.json')) && (await exists('package.json'))) {
+  try {
+    const manifest = JSON.parse(
+      await readFile(path.join(root, '.vr-cli.json'), 'utf8'),
+    )
+    const pkg = JSON.parse(
+      await readFile(path.join(root, 'package.json'), 'utf8'),
+    )
+    if (manifest.schemaVersion !== 1)
+      failures.push('manifest schemaVersion must equal 1')
+    if (typeof manifest.toolVersion !== 'string' || !manifest.toolVersion)
+      failures.push('manifest toolVersion must be a non-empty string')
+    if (manifest.preset !== 'viewer')
+      failures.push('manifest preset must equal viewer')
+    if (manifest.packageName !== pkg.name)
+      failures.push('manifest packageName must match package.json name')
+    if (!['portable', 'all', 'none'].includes(manifest.agentAssets))
+      failures.push('manifest agentAssets must be portable, all or none')
+    if (Number.isNaN(Date.parse(manifest.generatedAt)))
+      failures.push('manifest generatedAt must be an ISO-compatible date')
+    if (Object.prototype.hasOwnProperty.call(manifest, 'files'))
+      failures.push('manifest must not contain a files inventory')
+  } catch (error) {
+    failures.push(`.vr-cli.json: ${String(error)}`)
+  }
+}
+
+for (const relativePath of ['.nvmrc', '.node-version']) {
+  if (await exists(relativePath)) {
+    const actual = (
+      await readFile(path.join(root, relativePath), 'utf8')
+    ).trim()
+    if (actual !== nodeVersion)
+      failures.push(`${relativePath} must equal ${nodeVersion}`)
+  }
+}
+if (await exists('.npmrc')) {
+  const lines = new Set(
+    (await readFile(path.join(root, '.npmrc'), 'utf8'))
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter(Boolean),
+  )
+  for (const marker of [
+    'engine-strict=true',
+    'package-lock=true',
+    'save-prefix=>=',
+  ]) {
+    if (!lines.has(marker)) failures.push(`.npmrc must contain ${marker}`)
+  }
+}
+for (const [relativePath, markers] of [
+  [
+    'eslint.config.mjs',
+    [
+      "from '@eslint/js'",
+      "from 'typescript-eslint'",
+      "from 'eslint-plugin-react-hooks'",
+      'recommendedTypeChecked',
+      'tsconfig.server.json',
+      'globals.browser',
+      'globals.node',
+      "'react-hooks/rules-of-hooks'",
+      "'react-hooks/exhaustive-deps'",
+      'no-floating-promises',
+      'disableTypeChecked',
+    ],
+  ],
+  [
+    'prettier.config.mjs',
+    ['semi: false', 'singleQuote: true', "trailingComma: 'all'"],
+  ],
+  [
+    'tsconfig.json',
+    [
+      '"strict": true',
+      '"noUncheckedIndexedAccess": true',
+      '"noEmit": true',
+      '"include": ["src", "shared", "vite.config.ts"]',
+    ],
+  ],
+  [
+    'tsconfig.server.json',
+    [
+      '"strict": true',
+      '"erasableSyntaxOnly": true',
+      '"verbatimModuleSyntax": true',
+      '"exactOptionalPropertyTypes": true',
+      '"noUncheckedIndexedAccess": true',
+      '"types": ["node"]',
+      '"include": ["server", "shared"]',
+    ],
+  ],
+]) {
+  if (!(await exists(relativePath))) continue
+  const source = await readFile(path.join(root, relativePath), 'utf8')
+  for (const marker of markers) {
+    if (!source.includes(marker))
+      failures.push(`${relativePath} missing tooling marker: ${marker}`)
+  }
+}
+
+if (await exists('src/main.tsx')) {
+  const main = await readFile(path.join(root, 'src/main.tsx'), 'utf8')
+  const mainSource = stripSourceComments(main)
+  if (
+    countVaporCssImports(mainSource) !== 1 ||
+    mainSource.includes('@realsee/vapor/vapor.scss')
+  )
+    failures.push(
+      'Vapor CSS must use exactly one executable vapor.css side-effect import and must not use vapor.scss',
+    )
+  if (!mainSource.includes('./app/App'))
+    failures.push('main.tsx must compose the app layer')
+}
+
+if (await exists('src/vr/five/api.ts')) {
+  const api = stripSourceComments(
+    await readFile(path.join(root, 'src/vr/five/api.ts'), 'utf8'),
+  )
+  for (const entryPoint of fiveEntryPoints) {
+    if (!api.includes(`'${entryPoint}'`))
+      failures.push(`Five capability entry missing: ${entryPoint}`)
+  }
+}
+
+if (await exists('src/vr/plugins/dnalogel.ts')) {
+  const api = stripSourceComments(
+    await readFile(path.join(root, 'src/vr/plugins/dnalogel.ts'), 'utf8'),
+  )
+  if (!api.includes("from '@realsee/dnalogel'"))
+    failures.push('dnalogel preset root capability surface is missing')
+}
+
+if (await exists('src/vr/work/WorkSource.ts')) {
+  const source = stripSourceComments(
+    await readFile(path.join(root, 'src/vr/work/WorkSource.ts'), 'utf8'),
+  )
+  for (const marker of [
+    'resourceCodeFromPathname',
+    'window.location.pathname',
+    'segments.length !== 1',
+    '`/api/work/${encodeURIComponent(resourceCode)}`',
+    'asExplicitPanoTagList',
+    'hasCanonicalPanoTagData(value.contentType, value.data)',
+    'hasCanonicalPanoTagAnchor(value)',
+    'asRecord(envelope.presetData)',
+    'presetData: { panoTagList }',
+    'displayName: string',
+    'displayName: displayNameFrom(work.name) ?? workCode',
+    'modelFloorplan?: ModelFloorplanServerData',
+    'asModelFloorplanServerData(',
+    'asRecord(envelope.capabilities).modelFloorplan',
+    'modelFloorplan ? { capabilities: { modelFloorplan } } : {}',
+    'new RouteWorkSource()',
+  ]) {
+    if (!source.includes(marker))
+      failures.push(
+        `Route WorkSource or explicit preset marker missing: ${marker}`,
+      )
+  }
+  for (const marker of [
+    'VITE_WORK_URL',
+    '/work.json',
+    'envelope.tags',
+    'envelope.tagList',
+    'envelope.tag_list',
+    'payload.tags',
+  ]) {
+    if (source.includes(marker))
+      failures.push(
+        `WorkSource must not use a legacy URL/local Work or infer PanoTag from generic tags: ${marker}`,
+      )
+  }
+}
+
+for (const [relativePath, markers] of [
+  [
+    'shared/model-floorplan.ts',
+    [
+      'export function asModelFloorplanServerData(',
+      '!isInteger(value.version)',
+      'value.version < 0',
+      '!isFloorplanServerData(value.data)',
+      'value.outlines.length > 0',
+      'value.floor_datas.length > 0',
+      'isArrayOf(value.rooms, isRoom)',
+      'isRules(value.rules)',
+      'value.entrance === null || isEntrance(value.entrance)',
+      'isBounding(value.bounding)',
+      'isArrayOf(value.observers, isObserver)',
+      'isArrayOf(value.doors, isDoor)',
+    ],
+  ],
+  [
+    'server/types.ts',
+    [
+      'WorkCapabilities',
+      'modelFloorplan?: ModelFloorplanServerData',
+      'ModelFloorplanClient',
+      'RealseeSpatialClient',
+      'extends WorkDetailClient, ModelFloorplanClient',
+    ],
+  ],
+  [
+    'server/realsee-open-api.ts',
+    [
+      'implements RealseeSpatialClient',
+      "FLOORPLAN_PLUGINS_PATH = '/open/v3/floorplan/plugins'",
+      'asRecord(descriptor.data).format_floorplan_url',
+      "floorplanUrl.protocol !== 'https:'",
+      'floorplanUrl.username',
+      'floorplanUrl.password',
+      "redirect: 'error'",
+      'asModelFloorplanServerData(payload)',
+    ],
+  ],
+  [
+    'server/work-service.ts',
+    [
+      '.getModelFloorplan(resourceCode, { signal })',
+      '.catch((error: unknown) =>',
+      'modelFloorplan ? { capabilities: { modelFloorplan } } : {}',
+    ],
+  ],
+  [
+    'src/features/floorplan/ModelFloorplanFeature.ts',
+    [
+      '@realsee/dnalogel/libs/floorplan/ModelFloorplanPlugin',
+      'dnalogel.modelFloorplan',
+      'ModelFloorplanPlugin(five, { autoShowEnable: false })',
+      'plugins.register(PLUGIN_NAME, candidate)',
+      'candidate.dispose()',
+      'const modelSurface = five.getElement()',
+      'const wrapper = modelSurface?.parentElement',
+      'plugin.appendTo(wrapper)',
+      'plugin.load(serverData)',
+      'modelOpacity: 0',
+      'plugin.hide({ userAction: true })',
+      '.finally(restoreModelSurface)',
+      'if (!state.visible) restoreModelSurface()',
+      'plugins.unregister(PLUGIN_NAME, plugin)',
+      'stopStateChange()',
+      'if (disposeRequested) finalize()',
+      'if (!loading) finalize()',
+    ],
+  ],
+  [
+    'src/app/App.tsx',
+    [
+      'payload.capabilities?.modelFloorplan',
+      'if (modelFloorplan)',
+      'createModelFloorplanFeature(five, plugins)',
+      'await currentFloorplan.load(modelFloorplan)',
+      'currentFloorplan.dispose()',
+      'setFloorplanFeature(floorplan)',
+      'floorplan?.dispose()',
+    ],
+  ],
+  [
+    'src/features/navigation/ModeSwitcher.tsx',
+    [
+      'floorplan?.subscribeVisibility',
+      'await floorplan.show()',
+      'if (floorplan?.visible) await floorplan.hide()',
+      "floorplan?.visible ? 'floorplan' : tabFromFiveMode(five.currentMode)",
+      'Five.Mode.Panorama',
+      'Five.Mode.Mapview',
+    ],
+  ],
+]) {
+  if (!(await exists(relativePath))) continue
+  const source = stripSourceComments(
+    await readFile(path.join(root, relativePath), 'utf8'),
+  )
+  for (const marker of markers) {
+    if (!source.includes(marker))
+      failures.push(
+        `${relativePath} missing floorplan validation, capability or lifecycle marker: ${marker}`,
+      )
+  }
+}
+
+if (await exists('server/realsee-open-api.ts')) {
+  const source = stripSourceComments(
+    await readFile(path.join(root, 'server/realsee-open-api.ts'), 'utf8'),
+  )
+  if (source.includes('format_model_url'))
+    failures.push(
+      'floorplan descriptor must use format_floorplan_url, not format_model_url',
+    )
+}
+
+if (await exists('src/features/floorplan/ModelFloorplanFeature.ts')) {
+  const source = stripSourceComments(
+    await readFile(
+      path.join(root, 'src/features/floorplan/ModelFloorplanFeature.ts'),
+      'utf8',
+    ),
+  )
+  for (const [pattern, label] of [
+    [/plugin\.hooks\.on\(\s*['"]show['"]/, 'show hook'],
+    [/plugin\.hooks\.on\(\s*['"]hide['"]/, 'hide hook'],
+    [/plugin\.hooks\.on\(\s*['"]stateChange['"]/, 'stateChange hook'],
+  ]) {
+    if (!pattern.test(source))
+      failures.push(`ModelFloorplanFeature missing ${label}`)
+  }
+  if (/autoShowEnable\s*:\s*true/.test(source))
+    failures.push('ModelFloorplanFeature must keep autoShowEnable: false')
+  const appendTo = source.indexOf('plugin.appendTo(wrapper)')
+  const pluginLoad = source.indexOf('plugin.load(serverData)')
+  if (appendTo < 0 || pluginLoad < appendTo) {
+    failures.push(
+      'ModelFloorplanFeature must append plugin DOM to the Five host before loading format_floorplan_url data',
+    )
+  }
+  const stopShow = source.indexOf('stopShow()')
+  const stopHide = source.indexOf('stopHide()')
+  const stopStateChange = source.indexOf('stopStateChange()')
+  const pendingFinalize = source.indexOf('if (!loading) finalize()')
+  const finalizeStart = source.indexOf('const finalize =')
+  const finalizeRestore = source.indexOf('restoreModelSurface()', finalizeStart)
+  const unregister = source.indexOf(
+    'plugins.unregister(PLUGIN_NAME, plugin)',
+    finalizeStart,
+  )
+  if (
+    stopShow < 0 ||
+    stopHide < stopShow ||
+    stopStateChange < stopHide ||
+    pendingFinalize < stopStateChange ||
+    finalizeStart < 0 ||
+    finalizeRestore < finalizeStart ||
+    unregister < finalizeRestore
+  ) {
+    failures.push(
+      'ModelFloorplanFeature must restore the Five model surface on hide, failure and disposal, remove all hooks, then perform pending-load identity-safe cleanup',
+    )
+  }
+}
+
+if (await exists('src/features/navigation/ModeSwitcher.tsx')) {
+  const source = stripSourceComments(
+    await readFile(
+      path.join(root, 'src/features/navigation/ModeSwitcher.tsx'),
+      'utf8',
+    ),
+  )
+  for (const [pattern, label] of [
+    [
+      /type\s+ViewerTab\s*=\s*['"]tour['"]\s*\|\s*['"]model['"]\s*\|\s*['"]floorplan['"]/,
+      'three ViewerTab variants',
+    ],
+    [
+      /value\s*:\s*['"]tour['"]\s*,\s*text\s*:\s*['"]漫游['"]/,
+      'Panorama 漫游 tab',
+    ],
+    [
+      /value\s*:\s*['"]model['"]\s*,\s*text\s*:\s*['"]三维模型['"]/,
+      'Mapview 三维模型 tab',
+    ],
+    [
+      /\.\.\.\(\s*floorplan\s*\?\s*\[\{\s*value\s*:\s*['"]floorplan['"](?:\s+as\s+const)?\s*,\s*text\s*:\s*['"]平面图['"]\s*\}\]\s*:\s*\[\]\s*\)/,
+      'conditional 平面图 tab',
+    ],
+  ]) {
+    if (!pattern.test(source)) failures.push(`ModeSwitcher missing ${label}`)
+  }
+  const floorplanTabSyncCount =
+    source.match(
+      /floorplan\?\.visible\s*\?\s*['"]floorplan['"]\s*:\s*tabFromFiveMode\(five\.currentMode\)/g,
+    )?.length ?? 0
+  if (floorplanTabSyncCount < 2) {
+    failures.push(
+      'ModeSwitcher must sync its initial and failed-transition tabs from actual floorplan visibility',
+    )
+  }
+  if (
+    source.includes('Five.Mode.Topview') ||
+    /text\s*:\s*['"]地图['"]/.test(source)
+  ) {
+    failures.push('ModeSwitcher must not expose Topview as a 地图 tab')
+  }
+}
+
+if (await exists('src/features/tags/PanoTagFeature.ts')) {
+  const source = stripSourceComments(
+    await readFile(
+      path.join(root, 'src/features/tags/PanoTagFeature.ts'),
+      'utf8',
+    ),
+  )
+  for (const marker of [
+    "from '@realsee/dnalogel/libs/PanoTagPlugin'",
+    "const PLUGIN_NAME = 'dnalogel.panoTag'",
+    'const candidate = PanoTagPlugin(',
+    'plugins.register(PLUGIN_NAME, candidate)',
+    'candidate.dispose()',
+    "async load(panoTagList: Tags['tagList'])",
+    'plugin.load({ tagList: panoTagList })',
+    'const disposeError = plugins.unregister(PLUGIN_NAME, plugin)',
+  ]) {
+    if (!source.includes(marker))
+      failures.push(
+        `PanoTag compatibility, explicit type or ownership marker missing: ${marker}`,
+      )
+  }
+  for (const marker of [
+    'model_file',
+    "as Tags['tagList']",
+    "from '../../vr/work/WorkSource'",
+  ]) {
+    if (source.includes(marker))
+      failures.push(
+        `PanoTag must not use a non-canonical type or unchecked Work conversion: ${marker}`,
+      )
+  }
+}
+
+if (await exists('src/vr/plugins/examples/FeatureOwnedMeshPlugin.ts')) {
+  const source = stripSourceComments(
+    await readFile(
+      path.join(root, 'src/vr/plugins/examples/FeatureOwnedMeshPlugin.ts'),
+      'utf8',
+    ),
+  )
+  for (const marker of customPluginRequiredMarkers) {
+    if (!source.includes(marker))
+      failures.push(
+        `FeatureOwnedMeshPlugin ownership marker missing: ${marker}`,
+      )
+  }
+  for (const marker of customPluginForbiddenMarkers) {
+    if (source.includes(marker))
+      failures.push(
+        `FeatureOwnedMeshPlugin must not own Five runtime/render loop: ${marker}`,
+      )
+  }
+}
+
+for (const sourceFile of await collectSourceFiles('src')) {
+  const source = stripSourceComments(
+    await readFile(path.join(root, sourceFile), 'utf8'),
+  )
+  if (source.includes('@realsee/five/react')) {
+    failures.push(
+      `${sourceFile} must use the native Five API instead of @realsee/five/react`,
+    )
+  }
+  const serverOnlyMarker = findServerOnlyBrowserMarker(source)
+  if (serverOnlyMarker) {
+    failures.push(
+      `${sourceFile} must not read server-only config or credentials: ${serverOnlyMarker}`,
+    )
+  }
+  for (const [pattern, message] of threeR117Regressions) {
+    if (pattern.test(source)) failures.push(`${sourceFile}: ${message}`)
+  }
+}
+
+if (await exists('vite.config.ts')) {
+  const config = stripSourceComments(
+    await readFile(path.join(root, 'vite.config.ts'), 'utf8'),
+  )
+  const serverOnlyMarker = findServerOnlyBrowserMarker(config)
+  if (serverOnlyMarker || /envPrefix\s*:\s*[^\n]*REALSEE_/.test(config)) {
+    failures.push(
+      `vite.config.ts must not expose server-only config, AK/SK/token or REALSEE_*: ${serverOnlyMarker ?? 'envPrefix'}`,
+    )
+  }
+  const hostCount =
+    config.match(/\bhost\s*:\s*['"]127\.0\.0\.1['"]/g)?.length ?? 0
+  const portCount = config.match(/\bport\s*:\s*8087\b/g)?.length ?? 0
+  const strictPortCount =
+    config.match(/\bstrictPort\s*:\s*true\b/g)?.length ?? 0
+  const hasBffProxy = /target\s*:\s*['"]http:\/\/127\.0\.0\.1:8088['"]/.test(
+    config,
+  )
+  if (hostCount < 2 || portCount < 2 || strictPortCount < 2 || !hasBffProxy) {
+    failures.push(
+      'Vite must use strict IPv4 127.0.0.1:8087 and proxy /api to Fastify at 127.0.0.1:8088',
+    )
+  }
+}
+
+if (await exists('src/vr/five/SpatialRuntimeProvider.tsx')) {
+  const runtime = await readFile(
+    path.join(root, 'src/vr/five/SpatialRuntimeProvider.tsx'),
+    'utf8',
+  )
+  const runtimeSource = stripSourceComments(runtime)
+  if (
+    runtimeSource.includes('unsafe__useFiveInstance') ||
+    runtimeSource.includes('provider?.five')
+  ) {
+    failures.push('Spatial runtime must not obtain Five from a React wrapper')
+  }
+  if (
+    !/import\s*\{[^}]*\bFive\b[^}]*\}\s*from\s*['"]@realsee\/five['"]/.test(
+      runtimeSource,
+    )
+  ) {
+    failures.push(
+      'SpatialRuntimeProvider must import native Five from @realsee/five',
+    )
+  }
+  for (const marker of [
+    'new Five(',
+    '.appendTo(',
+    '.refresh(',
+    '.getElement()',
+    '.dispose()',
+    'new ResizeObserver',
+    'new SpatialRuntimeLifetime',
+    'runExclusive<T>(',
+    'ownedLifetime?.disposeFeatures()',
+    'ownedLifetime.afterPending(finalize)',
+    'width <= 0 || height <= 0',
+    'className="five-surface"',
+  ]) {
+    if (!runtimeSource.includes(marker))
+      failures.push(`Native Five lifecycle missing: ${marker}`)
+  }
+  const featureCleanup = runtimeSource.indexOf(
+    'ownedLifetime?.disposeFeatures()',
+  )
+  const deferredFinalize = runtimeSource.indexOf(
+    'ownedLifetime.afterPending(finalize)',
+  )
+  if (featureCleanup < 0 || deferredFinalize < featureCleanup) {
+    failures.push(
+      'Features must stop before pending native work, plugins, and Five are finalized',
+    )
+  }
+}
+
+if (await exists('src/app/App.tsx')) {
+  const app = await readFile(path.join(root, 'src/app/App.tsx'), 'utf8')
+  const appSource = stripSourceComments(app)
+  for (const marker of [
+    'lifetime.own(',
+    'lifetime.runExclusive(',
+    'await five.load(',
+    'await waitForActiveModel(',
+    'const panoTagList = payload.presetData?.panoTagList',
+    'if (panoTagList?.length)',
+    'await currentTags.load(panoTagList)',
+    'setWorkName(payload.displayName)',
+    'title={workName}',
+  ]) {
+    if (!appSource.includes(marker))
+      failures.push(
+        `App native async lifetime or explicit PanoTag condition missing: ${marker}`,
+      )
+  }
+  if (appSource.includes('payload.tags'))
+    failures.push('App must not load generic payload.tags as PanoTag')
+}
+
+if (await exists('src/ui/ViewerOverlay.tsx')) {
+  const overlay = stripSourceComments(
+    await readFile(path.join(root, 'src/ui/ViewerOverlay.tsx'), 'utf8'),
+  )
+  const missingOverlayComponents = viewerOverlayComponents.filter(
+    (component) =>
+      !hasVaporNamedImport(overlay, component) ||
+      !hasJsxElement(overlay, component),
+  )
+  if (missingOverlayComponents.length > 0) {
+    failures.push(
+      `ViewerOverlay must import and render the official Vapor demo components: ${missingOverlayComponents.join(', ')}`,
+    )
+  }
+  // Exact copy, class names and pixel placement are generator template fidelity,
+  // not project invariants. The generator asserts those against a freshly created
+  // project; enforcing them here would fail an owner who legitimately restyles
+  // their own overlay. Component fidelity and the invariants below stay.
+  for (const marker of viewerOverlayInvariantMarkers) {
+    if (!overlay.includes(marker))
+      failures.push(
+        `ViewerOverlay must keep the provider sizing, safe-area and accessible status invariants: ${marker}`,
+      )
+  }
+  for (const marker of viewerForbiddenOverlayMarkers) {
+    if (overlay.includes(marker))
+      failures.push(
+        `ViewerOverlay must not replace Vapor components with a raw title or custom glass styling: ${marker}`,
+      )
+  }
+}
+
+if (await exists('src/features/navigation/ModeSwitcher.tsx')) {
+  const modeSwitcher = stripSourceComments(
+    await readFile(
+      path.join(root, 'src/features/navigation/ModeSwitcher.tsx'),
+      'utf8',
+    ),
+  )
+  const missingModeSwitcherComponents = viewerModeSwitcherComponents.filter(
+    (component) =>
+      !hasVaporNamedImport(modeSwitcher, component) ||
+      !hasJsxElement(modeSwitcher, component),
+  )
+  if (missingModeSwitcherComponents.length > 0) {
+    failures.push(
+      `ModeSwitcher must import and render the official Vapor demo components: ${missingModeSwitcherComponents.join(', ')}`,
+    )
+  }
+  for (const marker of viewerModeSwitcherAccessibilityMarkers) {
+    if (!modeSwitcher.includes(marker))
+      failures.push(
+        `ModeSwitcher must keep its accessible grouping and responsive branching: ${marker}`,
+      )
+  }
+  for (const marker of viewerForbiddenModeSwitcherMarkers) {
+    if (modeSwitcher.includes(marker))
+      failures.push(
+        `ModeSwitcher must not regress to Segmented or old stretched/glass styling: ${marker}`,
+      )
+  }
+}
+
+for (const uiFile of await collectSourceFiles('src/ui')) {
+  const source = stripSourceComments(
+    await readFile(path.join(root, uiFile), 'utf8'),
+  )
+  const importsVrRuntime = /(?:from|import)\s*(?:\(\s*)?['"][^'"]*\/vr\//.test(
+    source,
+  )
+  if (
+    source.includes('@realsee/five') ||
+    source.includes('@realsee/dnalogel') ||
+    importsVrRuntime
+  ) {
+    failures.push(
+      `${uiFile} must not import src/vr, Five, or dnalogel spatial runtime`,
+    )
+  }
+}
+
+if (await exists('src/styles.css')) {
+  const styles = await readFile(path.join(root, 'src/styles.css'), 'utf8')
+  if (
+    !styles.includes('.five-surface') ||
+    !styles.includes('.dom-overlay') ||
+    !styles.includes('pointer-events: none')
+  ) {
+    failures.push(
+      'Native Five surface and DOM overlay must preserve independent layering and pointer-event isolation',
+    )
+  }
+  if (!styles.includes('pointer-events: auto')) {
+    failures.push(
+      'Visible overlay controls must re-enable pointer events with `pointer-events: auto`',
+    )
+  }
+  for (const marker of viewerForbiddenStyleMarkers) {
+    if (styles.includes(marker))
+      failures.push(
+        `Viewer styles must not override or redraw Vapor internals: ${marker}`,
+      )
+  }
+}
+
+if (await exists('.env.example')) {
+  const values = parseEnv(
+    await readFile(path.join(root, '.env.example'), 'utf8'),
+  )
+  for (const key of requiredEnvKeys) {
+    if (!values.has(key)) failures.push(`.env.example missing ${key}`)
+  }
+  for (const [key, value] of values) {
+    if (key.startsWith('VITE_WORK_'))
+      failures.push(
+        `${key} is obsolete; Work identity comes from /{resourceCode}`,
+      )
+    if (key.startsWith('VITE_') && isSensitiveKey(key))
+      failures.push(`${key} must not be browser-visible`)
+    if (
+      isSensitiveKey(key) &&
+      !secretEnvKeys.includes(key) &&
+      value &&
+      value !== '*'
+    ) {
+      failures.push(`${key} must be empty or use the * example placeholder`)
+    }
+  }
+  for (const key of credentialEnvKeys) {
+    const value = values.get(key)
+    if (value !== undefined && value !== '' && value !== '*') {
+      failures.push(`${key} must be empty or use the * example placeholder`)
+    }
+  }
+}
+
+if (await exists('.env.server.example')) {
+  failures.push(
+    'legacy .env.server.example must not exist; use the unified .env.example',
+  )
+}
+
+if (await exists('.gitignore')) {
+  const patterns = new Set(
+    (await readFile(path.join(root, '.gitignore'), 'utf8'))
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter(Boolean),
+  )
+  for (const pattern of ['.env*', '!.env.example']) {
+    if (!patterns.has(pattern))
+      failures.push(`.gitignore must contain ${pattern}`)
+  }
+}
+
+for (const [relativePath, markers] of [
+  [
+    'server/types.ts',
+    ['ServerConfig', 'WorkEnvelope', 'WorkDetailClient', 'WorkService'],
+  ],
+  [
+    'server/config.ts',
+    [
+      'loadServerConfig',
+      'REALSEE_GATEWAY_APP_KEY',
+      'REALSEE_GATEWAY_APP_SECRET',
+      "gatewayEndpoint.protocol !== 'https:'",
+      '): ServerConfig {',
+    ],
+  ],
+  [
+    'server/check-config.ts',
+    ['loadServerConfig()', 'BFF server configuration is valid.'],
+  ],
+  [
+    'server/realsee-open-api.ts',
+    [
+      'RealseeOpenApiClient',
+      'implements RealseeSpatialClient',
+      "ACCESS_TOKEN_PATH = '/auth/access_token'",
+      "'application/x-www-form-urlencoded'",
+      "WORK_INFO_PATH = '/open/v3/vr/info'",
+      'Authorization: accessToken',
+      'resource_code: resourceCode',
+      'UNAUTHORIZED_UPSTREAM_CODES',
+      'TOKEN_REFRESH_SKEW_MS',
+    ],
+  ],
+  [
+    'server/work-service.ts',
+    [
+      'createWorkService',
+      '): WorkService {',
+      'getWorkByResourceCode',
+      'openApiClient.getWorkDetail(resourceCode, { signal })',
+    ],
+  ],
+  [
+    'server/work-route.ts',
+    [
+      "'/api/work/:resourceCode'",
+      'getWorkByResourceCode(resourceCode, {',
+      'signal: requestAbort.signal',
+      'WORK_UPSTREAM_FAILED',
+    ],
+  ],
+  [
+    'server/app.ts',
+    [
+      'Fastify({ logger })',
+      "'/api/health'",
+      'fastifyStatic',
+      'serveFrontend',
+      "reply.sendFile('index.html')",
+      'Promise<FastifyInstance>',
+    ],
+  ],
+  [
+    'server/index.ts',
+    [
+      'loadServerConfig',
+      'RealseeOpenApiClient',
+      'createWorkService',
+      'createApp',
+      'app.listen({ host: config.host, port: config.port })',
+    ],
+  ],
+]) {
+  if (!(await exists(relativePath))) continue
+  const source = stripSourceComments(
+    await readFile(path.join(root, relativePath), 'utf8'),
+  )
+  for (const marker of markers) {
+    if (!source.includes(marker))
+      failures.push(
+        `${relativePath} missing Fastify BFF or Realsee OpenAPI contract: ${marker}`,
+      )
+  }
+}
+
+for (const relativePath of [
+  'AGENTS.md',
+  '.agents/skills/realsee-vr-app/SKILL.md',
+  '.agents/skills/realsee-image-resources/SKILL.md',
+]) {
+  if (!(await exists(relativePath))) continue
+  const source = await readFile(path.join(root, relativePath), 'utf8')
+  for (const marker of imageResourceGuidanceMarkers) {
+    if (!source.includes(marker))
+      failures.push(
+        `${relativePath} missing image resource domain, Five URL transform, 数据万象 or CORS rule: ${marker}`,
+      )
+  }
+}
+
+for (const [relativePath, routeMarkers] of [
+  // AGENTS.md is always-on context, so it keeps the full route contract. SKILL.md is a
+  // router and carries the two decisive rules plus a pointer to the contract.
+  ['AGENTS.md', routeGuidanceMarkers],
+  ['.agents/skills/realsee-vr-app/SKILL.md', routeSummaryMarkers],
+]) {
+  if (!(await exists(relativePath))) continue
+  const source = await readFile(path.join(root, relativePath), 'utf8')
+  for (const marker of spatialTagGuidanceMarkers) {
+    if (!source.includes(marker))
+      failures.push(
+        `${relativePath} missing spatial-tag decision or read-only rule: ${marker}`,
+      )
+  }
+  for (const marker of routeMarkers) {
+    if (!source.includes(marker))
+      failures.push(
+        `${relativePath} missing point/custom route selection, validation or lifecycle rule: ${marker}`,
+      )
+  }
+}
+
+for (const relativePath of [
+  'AGENTS.md',
+  '.agents/skills/realsee-vr-app/SKILL.md',
+  '.agents/skills/realsee-vr-app/references/vapor-dom-layer.md',
+]) {
+  if (!(await exists(relativePath))) continue
+  const source = await readFile(path.join(root, relativePath), 'utf8')
+  for (const marker of vaporGuidanceMarkers) {
+    if (!source.includes(marker))
+      failures.push(
+        `${relativePath} missing Vapor component fidelity rule: ${marker}`,
+      )
+  }
+}
+
+for (const [relativePath, markers, label] of [
+  [
+    '.agents/skills/realsee-vr-app/references/vapor-dom-layer.md',
+    vaporReferenceMarkers,
+    'versioned Vapor reference',
+  ],
+  [
+    '.agents/skills/realsee-vr-app/references/ui-and-validation.md',
+    vaporAcceptanceMarkers,
+    'Vapor runtime acceptance',
+  ],
+]) {
+  if (!(await exists(relativePath))) continue
+  const source = await readFile(path.join(root, relativePath), 'utf8')
+  for (const marker of markers) {
+    if (!source.includes(marker))
+      failures.push(`${relativePath} missing ${label} rule: ${marker}`)
+  }
+}
+
+if (
+  await exists(
+    '.agents/skills/realsee-vr-app/references/dnalogel-api-capabilities.md',
+  )
+) {
+  const source = await readFile(
+    path.join(
+      root,
+      '.agents/skills/realsee-vr-app/references/dnalogel-api-capabilities.md',
+    ),
+    'utf8',
+  )
+  for (const marker of [
+    'Spatial capability resolution order: installed @realsee/dnalogel preset -> native Five -> Three.js.',
+    'Tags, hotspots, and anchors default to PanoTagPlugin with GET /open/v3/hot/list.',
+    'Normalize optional OpenAPI configuration fields such as `version`, `globalConfig` and `contentTypeConfig`: treat `null` as absent before validating the installed SDK contract.',
+    'Load ordinary PanoTag point/plane tags after `five.load` without waiting for `five.model.loaded`; gate only model-dependent tag content or anchors on model readiness.',
+    'Tours use Five State snapshots with GET /open/v3/observerpicture/search.',
+    'Model annotations default to ModelMakerPlugin with GET /open/v3/annotation/search.',
+    'Routes use GuideLinePlugin for rendering and shape-selected CruisePlugin or MovePlugin playback with GET /open/v3/route/search.',
+    'Tour adapters read `data.list`, map each validated record to `Partial<State>` with the active `workCode`, and never cast an observer-picture record directly to `State`.',
+    'Model annotation adapters read `data.list`, validate `object_data` for `box`, `triangles` or `prism`, and pass `{ list }` to ModelMaker only for a model-capable Work.',
+    'Feature API, schema, or plugin failures disable only the affected feature; keep the base Viewer usable and never runtime-fallback to raw data or a custom Three implementation.',
+    'Scope tour, ModelMaker, GuideLine, Cruise and Move work to an active `workCode`/generation token; abort fetches, ignore stale continuations, pause the owned playback controller, remove hooks, clear GuideLine data, wait for pending loads, then let identity-safe unregister dispose each registered controller exactly once before `five.dispose()`.',
+    'SDK-shaped custom data requires an explicit developer opt-out from Open Platform data.',
+    '`model_file` is not canonical',
+    '`ModelTVVideoPlugin`',
+    '`CSS3DRenderPlugin.create3DDomContainer`',
+    '`PanoVideoPlugin`',
+    'generic `tags`, `tagList` and `tag_list`',
+    '`ServerData` with `box`, `triangles` or `prism` items',
+    ...routeGuidanceMarkers,
+  ]) {
+    if (!source.includes(marker))
+      failures.push(
+        `dnalogel capability map missing capability order, data source or plugin route: ${marker}`,
+      )
+  }
+}
+
+for (const [relativePath, markers] of [
+  [
+    '.agents/skills/realsee-vr-app/references/five-runtime.md',
+    routeGuidanceMarkers.slice(4, 6),
+  ],
+  [
+    '.agents/skills/realsee-vr-app/references/plugin-lifecycle.md',
+    routeGuidanceMarkers.slice(6, 8),
+  ],
+  [
+    '.agents/skills/realsee-vr-app/references/official-docs.md',
+    routeGuidanceMarkers.slice(2, 4),
+  ],
+]) {
+  if (!(await exists(relativePath))) continue
+  const source = await readFile(path.join(root, relativePath), 'utf8')
+  for (const marker of markers) {
+    if (!source.includes(marker))
+      failures.push(`${relativePath} missing route contract marker: ${marker}`)
+  }
+}
+
+for (const [relativePath, markers] of [
+  [
+    '.agents/skills/realsee-vr-app/references/dnalogel-api-capabilities.md',
+    floorplanGuidanceMarkers,
+  ],
+  ['AGENTS.md', floorplanSummaryMarkers],
+  ['.agents/skills/realsee-vr-app/SKILL.md', floorplanSummaryMarkers],
+  [
+    '.agents/skills/realsee-vr-app/references/five-runtime.md',
+    [floorplanPointerMarker],
+  ],
+  [
+    '.agents/skills/realsee-vr-app/references/official-docs.md',
+    [floorplanPointerMarker],
+  ],
+  [
+    '.agents/skills/realsee-vr-app/references/plugin-lifecycle.md',
+    [floorplanPointerMarker],
+  ],
+  [
+    '.agents/skills/realsee-vr-app/references/ui-and-validation.md',
+    [floorplanPointerMarker],
+  ],
+]) {
+  if (!(await exists(relativePath))) continue
+  const source = await readFile(path.join(root, relativePath), 'utf8')
+  for (const marker of markers) {
+    if (!source.includes(marker))
+      failures.push(
+        `${relativePath} missing floorplan endpoint, validation, tab, multi-floor or cleanup rule: ${marker}`,
+      )
+  }
+}
+
+if (warnings.length) {
+  console.warn(warnings.map((warning) => `! ${warning}`).join('\n'))
+}
+
+if (failures.length) {
+  console.error(failures.map((failure) => `- ${failure}`).join('\n'))
+  process.exitCode = 1
+} else {
+  console.log(`Realsee spatial project verification passed: ${root}`)
+}