> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acondawayuno.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 上的生产构建。

<AccordionGroup>
  <Accordion title="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:

    ```bash theme={null}
    git status --short
    npm run typecheck
    npm run lint
    npm test
    ```

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

    <Warning>
      `/?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.
    </Warning>
  </Accordion>

  <Accordion title="'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`.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="'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:

    ```bash theme={null}
    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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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](/content/content-studio), [Scene
layout](/content/scene-layout), and [GLB models](/customization/glb-models) for
the complete workflows.