Show detected objects runtime toggle implementation plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Add runtime.showDetectedObjects to control detected object visibility at runtime, with default behavior unchanged (true).

Architecture: Extend runtime schema and defaults, then subscribe to the new runtime field inside DetectedObjectManager to toggle LAYER_DETECTED_OBJECT.visible. Keep drawDetectedObjects() data sync logic unchanged so visibility control stays independent from object CRUD.

Tech Stack: TypeScript, PIXI.js 8 layer containers, Valtio subscribeKey, VitePress docs.

---

Constraints and scope

This plan follows these constraints:

• Implement only the requested feature.
• Do not add or run dedicated feature tests (explicit user request).
• Keep project-required static verification (npm run lint, npx tsc --noEmit).
• Do not create commits unless the user explicitly requests a commit.

Task 1: Add runtime type field

Files:

• Modify: src/core/@types/index.d.ts:639-651

Step 1: Add showDetectedObjects to RuntimeConfig

Insert a new boolean field near existing visibility toggles:

/** 是否显示 AI 检测物体 */
showDetectedObjects: boolean

Step 2: Keep property order stable in visibility section

Place showDetectedObjects after showCarpet so related runtime flags stay clustered.

Task 2: Add runtime default value

Files:

• Modify: src/core/constant/config.ts:635-651

Step 1: Add default value in DEFAULT_RUNTIME_CONFIG

showCarpet: true,
showDetectedObjects: true,
showChargingStationRing: false,

Step 2: Keep backward-compatible default behavior

Ensure the default is true so existing integrations continue to display objects without additional config.

Task 3: Add manager-level visibility subscription

Files:

• Modify: src/core/managers/DetectedObjectManager.ts:1-121

Step 1: Add Valtio subscription import

import { subscribeKey } from 'valtio/vanilla/utils'

Step 2: Add unsubscribe holder

private unsubscribeShowDetectedObjects: (() => void) | null = null

Step 3: Initialize layer visibility from runtime in constructor

constructor(private appService: AppService) {
  this.applyLayerVisibility(this.appService.runtime.showDetectedObjects)

  this.unsubscribeShowDetectedObjects = subscribeKey(
    this.appService.runtime,
    'showDetectedObjects',
    (showDetectedObjects: boolean) => {
      this.applyLayerVisibility(showDetectedObjects)
    },
  )
}

Step 4: Add private layer visibility helper

private applyLayerVisibility(visible: boolean): void {
  const detectedObjectLayer = this.appService.appContainer.getLayer(
    LAYER_DETECTED_OBJECT,
  )

  if (detectedObjectLayer) {
    detectedObjectLayer.visible = visible
  }
}

Step 5: Keep draw flow unchanged

Do not add early returns in drawDetectedObjects(). Hidden state must not prevent object data from being created or updated.

Step 6: Clean up subscription in destroy()

destroy(): void {
  if (this.unsubscribeShowDetectedObjects) {
    this.unsubscribeShowDetectedObjects()
    this.unsubscribeShowDetectedObjects = null
  }

  this.clearAllDetectedObjects()
}

Task 4: Update runtime reference documentation

Files:

• Modify: docs/reference/runtime.md

Step 1: Add showDetectedObjects entry

Add a new section consistent with existing runtime docs style:

## showDetectedObjects

- **类型**: `boolean`
- **默认值**: `true`

是否显示 AI 检测物体。

Step 2: Update runtime sample block

Add showDetectedObjects: true to the top sample runtime object so the new field is discoverable.

Task 5: Add traceability record

Files:

• Create: docs/records/plans/2026-03-04-detected-objects-visibility-plan.md

Step 1: Write plan record with required sections

Include:

1. Background.
2. Goal and scope.
3. Chosen approach.
4. Impacted files/modules.
5. Verification checklist.

Step 2: Keep record language in English

Follow repository traceability requirement for plan/bug records.

Task 6: Run required verification commands

Files:

• Modify: none

Step 1: Run lint

Run: npm run lint Expected: no new lint errors.

Step 2: Run TypeScript check

Run: npx tsc --noEmit Expected: no new type errors.

Task 7: Final review checklist

Files:

• Modify: none

Step 1: Confirm requested behavior

Verify by inspection that:

• runtime.showDetectedObjects exists and defaults to true.
• Toggling runtime field changes LAYER_DETECTED_OBJECT.visible.
• Existing detected object draw/update/remove logic is unchanged.

Step 2: Prepare summary for user

Report changed files and behavior impact with file references.