reso-inventory-viewer: Instructions file for Claude Code

CLAUDE.md — engineering notes for reso-inventory-viewer

These notes are written for future agents (and humans) modifying this repo. They capture the load-bearing pieces of the architecture, the gotchas that keep biting, and the conventions to follow when adding features.

Tech stack

• Next.js 16 App Router, static export (output: 'export', distDir: 'build').
• React 19, all components are client components ("use client").
• Redux Toolkit with buildCreateSlice + the async-thunk creator.
• react-bootstrap 5 for layout and form controls.
• react-force-graph-2d (built on force-graph / d3-force) for the visualizer.
• @table-library/react-table-library for the virtualized record table.

The app is fully client-side after the initial HTML shell — there is no server data. next-redux-wrapper is intentionally not used; the Redux store is created once at module load (features/store.ts) and provided in app/layout.tsx.

Data model (manifestSlice)

The Redux state shape is:

{
  records: Record<string, ResoRecord>,    // by id
  assets:  Record<string, ResoAssetBundle>, // by synthetic bundle id
  selectedRecords: string[],              // sorted, unique
  filter: { showObjects, showWorlds, showMessages, showAvatar, showResoniteProvidedAssets },
  loading, error
}

A ResoRecord is one of object | world | audio | texture. An ResoAssetBundle groups assets that are referenced by exactly the same set of records (plus the Resonite-provided flag). Bundles are the unit of "shared cost": if every referencing record is deleted, the entire bundle goes with it.

Key invariants:

• selectedRecords is always sorted and de-duplicated. Use _.sortedIndexOf / _.sortedIndex to query / insert.
• Selectors created with createSelector (e.g. filteredRecords, filteredAssets) memoize on input identity. Don't replace them with inline useMemo over useAppSelector-returned arrays unless you understand the re-render implications.
• internalAssets is the per-record bundle (assets only that record references and which Resonite does not provide). Everything else is modeled as a shared bundle, even if only one record refers to it but Resonite provides it.