# Storybook Importer Cache

- Status: `completed`
- Owner: `codex`
- Date: `2026-03-25`

## Goal

Prevent Storybook from serving a stale Vite importer map after story files are added or removed,
which currently causes runtime failures like `importers[path] is not a function` even though the
story index already references the new file.

## Scope

- In scope:
  - diagnose the mismatch between `index.json` and the virtual `storybook-stories.js` importer map
  - update Storybook's Vite cache strategy so story file set changes invalidate the cache
  - verify the runtime importer map and story index agree after the config change
- Out of scope:
  - changing component implementations or Storybook story content
  - broader Storybook architecture changes unrelated to cache invalidation

## Constraints

- Keep the repo-local Storybook cache under `.artifacts/`.
- Prefer invalidating on story file set changes, not on every edit, so normal dev caching remains useful.
- Avoid introducing new package dependencies just to compute a cache key.

## Affected Surfaces

- `docs/exec-plans/2026-03-25-storybook-importer-cache.md`
- `apps/docs/.storybook/main.ts`

## Plan

1. Record the importer/index mismatch and confirm it is cache-related.
2. Derive the Storybook Vite cache directory from the current story file set.
3. Restart Storybook and verify the virtual importer map matches `index.json`.

## Validation

- `pnpm dev:docs`
- compare `http://127.0.0.1:<port>/index.json` against `http://127.0.0.1:<port>/@id/__x00__virtual:/@storybook/builder-vite/storybook-stories.js`

## Status Log

- `2026-03-25 15:31` Confirmed a runtime mismatch: `index.json` references `./src/components/gauge.stories.tsx`, but the cached virtual `storybook-stories.js` importer map does not include it.
- `2026-03-25 15:38` Updated Storybook's Vite cache directory to include a hash of the current story file set so added or removed story files invalidate the cache instead of reusing a stale importer map.
- `2026-03-25 15:42` Restarted Storybook and verified `index.json` and the virtual importer map both report 47 story import paths, including `gauge.stories.tsx` and `input-group.stories.tsx`.
- `2026-03-25 15:47` Verified `pnpm harness:validate:docs` and `pnpm --dir apps/docs run typecheck`; also fixed the local `revenue-dashboard` navigation item typing so docs typecheck returns cleanly.