Troubleshooting

Diagnose Content Studio saves, stale browser drafts, scene mismatches, GLB placeholders, lighting, and React renderer warnings.

Use the checks below in order. They distinguish a temporary Studio preview from source-controlled files and a deployed build.

按顺序检查。重点是区分 Content Studio 临时预览、代码仓库中的文件，以及 Cloudflare 上的生产构建。

The published layout does not match Content Studio / 发布布局与 Studio 不一致

A scene edit reaches production only after all four checkpoints succeed:

1. Finish dragging with Confirm all placement.
2. Select Save to project.
3. Commit the generated files and referenced uploads.
4. Push to main and wait for the GitHub Actions deployment to pass.

保存成功后，以下两份场景数据应一致：

• public/content/site-content.json contains the complete editable document.
• app/generated/scene-config.ts contains the production scene snapshot.

Run:

git status --short
npm run typecheck
npm run lint
npm test

Include both files and any new public/uploads/** assets in the commit.

/?studio=1 may restore localStorage["living-index.content-draft.v1"]. That browser draft is intentionally limited to the authoring route. Open / without studio=1 to inspect the committed result, or use Reset draft before starting a new Studio session.

'Save to project' is unavailable / “保存到项目”不可用

The write endpoint exists only in the local Vite development server. It is not included in a production build.

1. Start the repository with npm run dev.
2. Open the loopback URL shown by Vite with ?studio=1.
3. Use localhost, an address in 127.0.0.0/8, or ::1. LAN and public hosts are rejected.
4. Finish any active placement or model upload before saving.
5. Resolve invalid social or card links reported by the Studio.

JSON export is a portability tool, not the complete project-save transaction. Importing or copying JSON alone does not include binary uploads or regenerate app/generated/scene-config.ts.

A GLB stays as a placeholder / GLB 一直显示占位物

The load indicator moves through fetching, processing, ready, or error. A short placeholder period is expected while the GLB is parsed, fitted, and compiled by the GPU.

If it never becomes ready:

• Confirm the file is a self-contained glTF 2.0 binary .glb.
• Re-export without external textures, Draco, Meshopt, or KTX2/Basis dependencies.
• Check the Studio error message for structural, geometry, or texture-budget failures.
• Keep the tab open until the upload and first parse finish.
• Verify the resulting URL is a same-origin /uploads/models/<uuid>.glb path.

A newly uploaded model first lives in .content-studio-cache/models/. It is intentionally absent from public/uploads/models/ until Save to project succeeds. Removing it before saving discards the staged file.

For a built-in replacement, the native object remains visible while the GLB loads or if loading fails. For a new custom object, the scene keeps a visible loading/error placeholder so placement remains editable.

A GLB is dark or ignores the room light / GLB 偏暗或不响应光照

The room lights affect standard lit PBR materials. They cannot make an unlit/basic material respond to light, and a strongly emissive material may appear almost unchanged between day and night.

In the authoring tool:

• use Principled BSDF before export;
• embed Base Color, Roughness, Metallic, and Normal textures;
• mark Base Color as sRGB;
• prefer OpenGL normal maps;
• apply rotation and scale before export;
• inspect normals and avoid unintentionally high metallic values.

The Studio accent color controls the interaction marker and presentation accents. It does not rewrite the GLB material or repair its lighting model.

'Detected multiple renderers concurrently rendering the same context provider'

This is a React context warning, not a glTF validation error and not a statement that one GLB created too many WebGL contexts.

It commonly appears when HMR temporarily keeps two React renderer trees, or when duplicate React packages/providers are mounted during development. First stop duplicate dev servers or embedded previews, then restart:

npm run dev

If it persists, check that the page mounts one application root and that npm ls react react-dom resolves the intended versions. Also inspect recent provider changes instead of repeatedly re-uploading the model.

The room already cancels its animation loop, listeners, controls, loaders, scene resources, renderer, and canvas during unmount. A warning that survives a clean restart therefore warrants checking renderer/provider duplication rather than GLB contents.

The room is blank or an object cannot be selected / 房间空白或物体无法点击

For a blank room, inspect the Console for WebGL initialization or context loss errors, enable hardware acceleration, and retry in a current browser. The semantic index remains available when WebGL fails.

For selection:

• only enabled, interactive assets open a content panel;
• decorative custom assets are intentionally non-interactive;
• disabled built-ins are removed from both the room and interactive index;
• a gesture moving more than about 6 px with a mouse or 11 px with touch is treated as a camera drag.

Use the index as the accessible path to every active interactive chapter.

General diagnostic order / 通用排查顺序

1. Reproduce on / and /?studio=1 separately.
2. Check the Console and Network panels.
3. Check git status --short for the JSON, generated scene module, and uploads.
4. Run the local validation commands.
5. Confirm the GitHub Actions run for the pushed commit completed successfully.
6. Test a private window only when you need to rule out extensions or browser storage; do not erase unrelated browser data as a first step.

See Content Studio, Scene layout, and GLB models for the complete workflows.