Run 1: View and Fallback

Mock data infrastructure, GEN-MEDIA-0003 (View Entity Image) stories, and verification of existing Item stories after the ImageCellDisplay swap.

Entry Criteria

#	Criterion	Verification Command	Expected Output
1	On branch jmpicnic/uc-stories (created from jmpicnic/item-image-upload-components)	git -C <worktree> branch --show-current	jmpicnic/uc-stories
2	Branch up-to-date with base	git -C <worktree> fetch origin jmpicnic/item-image-upload-components && git -C <worktree> merge-base --is-ancestor origin/jmpicnic/item-image-upload-components HEAD	Exit 0
3	Storybook builds	npm run build-storybook --prefix <ux-prototype>	Exit code 0
3	All unit tests pass	npm run test --prefix <ux-prototype>	Exit code 0
4	Lint passes	npm run lint --prefix <ux-prototype>	Exit code 0
5	Component mock data exists	test -f <ux-prototype>/src/components/canary/__mocks__/image-story-data.ts	Exit code 0

Artifact Specifications

Artifact	Path	Format	Description
Use-case mock data	src/use-cases/general-behaviors/entity-media/_shared/mock-data.ts	TypeScript	File/Blob mocks, URL mocks, upload variants
Section description	entity-media/description.mdx	MDX	Entity Media section (placeholder — finalized in Run 4)
View UC description	view-entity-image/description.mdx	MDX	View Entity Image use case description
3 scenario descriptions	view-entity-image/0001-view-in-grid/description.mdx, 0002-inspector-overlay/description.mdx, 0003-thumbnail-fallback/description.mdx	MDX	One per scenario
10 story files	view-entity-image/{0001,0002,0003}-*/*.stories.tsx	TypeScript	See task list below

Task List

#	Task	Persona	Depends On	Status	Acceptance Criteria
1.1	Create directory structure: entity-media/, _shared/, set-entity-image/, remove-entity-image/, view-entity-image/ with scenario subdirectories (0001-view-in-grid/, 0002-inspector-overlay/, 0003-thumbnail-fallback/)	fe	—	Pending	Directories exist
1.2	Create _shared/mock-data.ts with all use-case-specific mock objects (MOCK_FILE_JPEG, MOCK_FILE_PNG, MOCK_FILE_OVERSIZED, MOCK_FILE_BMP, MOCK_CLIPBOARD_IMAGE_BLOB, MOCK_EXTERNAL_URL, MOCK_EXTERNAL_URL_BROKEN, MOCK_EXTERNAL_URL_NON_IMAGE, mockUploadSlow, mockUploadFail)	fe	1.1	Pending	File exports all listed mocks, TypeScript compiles
1.3	Create entity-media/description.mdx section description (stub — finalized in Run 4)	fe	1.1	Pending	MDX renders in Storybook sidebar
1.4	Create view-entity-image/description.mdx use case description with scenarios table	fe	1.1	Pending	MDX renders, links to specification
1.5	Create 0001-view-in-grid/description.mdx scenario description	fe	1.1	Pending	MDX renders
1.6	Create 0002-inspector-overlay/description.mdx scenario description	fe	1.1	Pending	MDX renders
1.7	Create 0003-thumbnail-fallback/description.mdx scenario description	fe	1.1	Pending	MDX renders
1.8	0001-view-in-grid/grid-thumbnails.stories.tsx — AG Grid with ImageCellDisplay, mixed image states	fe	1.2	Pending	Story renders, play function passes
1.9	0001-view-in-grid/hover-preview.stories.tsx — hover popover	fe	1.2	Pending	Story renders, play function verifies popover
1.10	0001-view-in-grid/playground.stories.tsx — argTypes controls	fe	1.2	Pending	Story renders with controls
1.11	0002-inspector-overlay/open-and-close.stories.tsx — modal open/dismiss	fe	1.2	Pending	Story renders, play function exercises 3 dismiss methods
1.12	0002-inspector-overlay/edit-transition.stories.tsx — Edit button flow	fe	1.2	Pending	Story renders, play function verifies transition
1.13	0002-inspector-overlay/no-edit.stories.tsx — read-only inspector	fe	1.2	Pending	Story renders, no Edit button visible
1.14	0003-thumbnail-fallback/error-badge.stories.tsx — broken URL error state	fe	1.2	Pending	Story renders error badge on placeholder
1.15	0003-thumbnail-fallback/loading-shimmer.stories.tsx — shimmer transition	fe	1.2	Pending	Story renders shimmer then loaded image
1.16	0003-thumbnail-fallback/no-image.stories.tsx — null imageUrl placeholder	fe	1.2	Pending	Story renders initials placeholder, no error badge
1.17	0003-thumbnail-fallback/playground.stories.tsx — state controls	fe	1.2	Pending	Story renders with controls for image states
1.18	Verify existing ITM-0001 story — grid renders with ImageCellDisplay	fe	1.8	Pending	Existing play function passes, thumbnails visible
1.19	Verify existing ITM-0002 story — details drawer with image column	fe	1.8	Pending	Existing play function passes
1.20	Verify existing ITM-0004 story — inline edit still works	fe	1.8	Pending	Existing play function passes
1.21	Wave gate: lint, tsc, build-storybook, test, VRT	fe	1.8–1.20	Pending	All checks pass, VRT baselines updated
1.22	Quality review of all new files	qr	1.21	Pending	No anti-patterns, consistent style, description.mdx in every scenario dir

Internal Dependency Graph

1.1 (dirs + scenario subdirs)
 ├─► 1.2 (mock data)
 ├─► 1.3 (entity-media description.mdx stub)
 ├─► 1.4 (view-entity-image description.mdx)
 └─► 1.5–1.7 (3 scenario description.mdx, parallelizable)
      │
      ▼
1.8–1.17 (10 stories, parallelizable)
      │
      ▼
1.18–1.20 (verification of existing stories, parallelizable)
      │
      ▼
1.21 (wave gate)
      │
      ▼
1.22 (quality review)

Tasks 1.5–1.7 (scenario MDX) can run in parallel. Tasks 1.8–1.17 can be implemented in parallel by multiple front-end agents. Tasks 1.18–1.20 can run in parallel after at least one grid story renders.

Exit Criteria

#	Criterion	Verification Command	Expected Output
1	10 new story files exist	find <ux-prototype>/src/use-cases/general-behaviors/entity-media/view-entity-image -name '*.stories.tsx' | wc -l	10
2	5 description.mdx files exist (1 section + 1 UC + 3 scenarios)	find <ux-prototype>/src/use-cases/general-behaviors/entity-media -name 'description.mdx' | wc -l	5
3	3 scenario directories exist	ls -d <ux-prototype>/src/use-cases/general-behaviors/entity-media/view-entity-image/0001-* <ux-prototype>/src/use-cases/general-behaviors/entity-media/view-entity-image/0002-* <ux-prototype>/src/use-cases/general-behaviors/entity-media/view-entity-image/0003-* 2>/dev/null | wc -l	3
4	Mock data file exists	test -f <ux-prototype>/src/use-cases/general-behaviors/entity-media/_shared/mock-data.ts	Exit 0
4	Lint passes	npm run lint --prefix <ux-prototype>	Exit 0
5	TypeScript compiles	npx tsc --noEmit --project <ux-prototype>	Exit 0
6	Storybook builds	npm run build-storybook --prefix <ux-prototype>	Exit 0
7	Unit tests pass	npm run test --prefix <ux-prototype>	Exit 0
8	VRT baselines current	npx playwright test --project=vrt --prefix <ux-prototype>	Exit 0
9	Rebased onto base branch	git -C <worktree> fetch origin jmpicnic/item-image-upload-components && git -C <worktree> rebase origin/jmpicnic/item-image-upload-components	Exit 0, no conflicts
10	Post-rebase checks pass (lint, tsc, build, test)	Re-run criteria 5–8 after rebase	All pass

Agent Prompt Templates

Front-End Engineer — fe-view-stories

Implement Storybook use case stories for GEN-MEDIA-0003 (View Entity Image) in the ux-prototype repository. Working directory: <worktree-path>.

Read the specification at documentation/src/content/docs/roadmap/reference-data/item/item-image-upload/ux-design/use-cases/specification.md — section “GEN::MEDIA::0003 — View Entity Image”.

Follow the conventions in the specification: sidebar title format, MDX template, story artifact pattern (primary + playground), mock data from _shared/mock-data.ts.

Use only canary components — zero vendored imports. Compose ImageDisplay, ImageCellDisplay, ImageHoverPreview, ImageInspectorOverlay from @/components/canary/. Follow existing story patterns in src/use-cases/reference/items/browse-and-search/view-items-list.stories.tsx.

Quality Reviewer — qr-view-stories

Review all new files in src/use-cases/general-behaviors/entity-media/ for: coding standards, consistent imports (canary only, no vendored/extras), MDX formatting (HTML tables, numeric entities, no bare braces), story title conventions, play function coverage.

Handoff

Artifacts Consumed (from previous runs)

Artifact	Source Run	Path
Component implementations	Pre-existing (branch jmpicnic/item-image-upload-components, PR #63)	src/components/canary/
Component mock data	Pre-existing	src/components/canary/__mocks__/image-story-data.ts

Artifacts Produced (for subsequent runs)

Artifact	Consumer Run	Path
Use-case mock data	Runs 2, 3, 4	src/use-cases/general-behaviors/entity-media/_shared/mock-data.ts
Directory structure	Runs 2, 3, 4	src/use-cases/general-behaviors/entity-media/
Updated VRT baselines	Runs 2, 3, 4	VRT snapshot directory