Run 1: Infrastructure and Scaffolding

This run covers Wave 0a (dependency and environment verification) and Wave 0b (structural scaffolding). It produces no new user-facing components but establishes every shared foundation that Runs 2-4 depend on: the utilities directory, shared types, canvas helpers, ShadCN primitives, Badge extension, mock data, and the full directory scaffold.

Entry Criteria

#	Criterion	Verification Command	Expected Output
1	main is up-to-date with origin	git -C /Users/jmp/code/arda/image-components-worktrees/run-1 fetch origin && git -C /Users/jmp/code/arda/image-components-worktrees/run-1 diff origin/main jmpicnic/item-image-upload-components --stat	Empty diff — no lines changed
2	Worktree exists at image-components-worktrees/run-1 on branch jmpicnic/item-image-upload-components	git -C /Users/jmp/code/arda/image-components-worktrees/run-1 branch --show-current	jmpicnic/item-image-upload-components
3	Existing lint check passes	npm --prefix /Users/jmp/code/arda/image-components-worktrees/run-1 run lint	Exit 0, zero warnings
4	Existing Storybook build passes	npm --prefix /Users/jmp/code/arda/image-components-worktrees/run-1 run build-storybook	Exit 0
5	Existing unit test suite passes	npm --prefix /Users/jmp/code/arda/image-components-worktrees/run-1 run test	Exit 0, all tests green

Artifact Specifications

#	Artifact	Path	Format / Schema
A1	Utilities directory	src/types/canary/utilities/	Directory containing TypeScript modules and barrel
A2	Utility types module	src/types/canary/utilities/image-field-config.ts	.ts — exports: ImageMimeType, ImageFieldStaticConfig, ImageFieldInitConfig, ImageFieldConfig, ImageInput, ImageUploadResult, CropData, PixelCrop
A3	Utilities barrel	src/types/canary/utilities/index.ts	.ts — re-exports all from utils, pagination, date-time, image-field-config, get-initials, get-cropped-image
A4	getInitials helper	src/types/canary/utilities/get-initials.ts	.ts — named export getInitials(name: string): string
A5	getInitials tests	src/types/canary/utilities/get-initials.test.ts	Vitest — 8 tests
A6	getCroppedImage helper	src/types/canary/utilities/get-cropped-image.ts	.ts — named export getCroppedImage(imageSrc: string, pixelCrop: PixelCrop): Promise<Blob>
A7	getCroppedImage tests	src/types/canary/utilities/get-cropped-image.test.ts	Vitest — 5 tests
A8	Utilities MDX page	src/types/canary/utilities/utilities.mdx	Storybook MDX — prose overview with Canvas embeds for getInitials and getCroppedImage
A9	alert-dialog primitive	src/components/canary/primitives/alert-dialog.tsx	ShadCN primitive, Radix UI
A10	checkbox primitive	src/components/canary/primitives/checkbox.tsx	ShadCN primitive, Radix UI
A11	popover primitive	src/components/canary/primitives/popover.tsx	ShadCN primitive, Radix UI
A12	progress primitive	src/components/canary/primitives/progress.tsx	ShadCN primitive, Radix UI
A13	slider primitive	src/components/canary/primitives/slider.tsx	ShadCN primitive, Radix UI
A14	aspect-ratio primitive	src/components/canary/primitives/aspect-ratio.tsx	ShadCN primitive, Radix UI
A15	Badge error-overlay variant	src/components/canary/atoms/badge/badge-base.tsx	CVA variant addition — error-overlay entry in variant map
A16	Badge unit tests	src/components/canary/atoms/badge/badge-base.test.tsx	Vitest — 4 new tests for error-overlay variant
A17	Badge updated stories	src/components/canary/atoms/badge/badge-base.stories.tsx	3 new stories + updated Playground and AllVariants
A18	Mock data module	src/components/canary/__mocks__/image-story-data.ts	.ts — exports: MOCK_ITEM_IMAGE, MOCK_ITEMS, ITEM_IMAGE_CONFIG, mockUpload, mockReachabilityCheck
A19	Molecule directory scaffold	src/components/canary/molecules/form/index.ts and siblings	Empty barrel index.ts in each of: form/, image-display/, image-drop-zone/, image-preview-editor/, image-hover-preview/, image-inspector-overlay/, image-comparison-layout/
A20	Atom directory scaffold	src/components/canary/atoms/grid/image/index.ts and atoms/copyright-acknowledgment/index.ts	Empty barrel index.ts in each
A21	Organism directory scaffold	src/components/canary/organisms/shared/image-upload-dialog/index.ts	Empty barrel index.ts
A22	Skeleton shimmer verification	src/components/canary/primitives/skeleton.tsx + src/styles/globals.css	@keyframes shimmer present in @theme block; Skeleton renders animated shimmer
A23	Primitive context stories — Skeleton	src/components/canary/primitives/skeleton-image.stories.tsx	3 stories: Default, ImagePlaceholder, GalleryGrid
A24	Primitive context stories — Tabs	src/components/canary/primitives/tabs-image.stories.tsx	2 stories: Default, ImageDetailTabs
A25	Primitive context stories — AlertDialog	src/components/canary/primitives/alert-dialog-image.stories.tsx	2 stories: Default, DeleteConfirmation

Task List

#	Task	Persona	Depends On	Status	Acceptance Criteria
1.1	Verify and update dependencies to latest compatible minor/patch versions	front-end-engineer	—	Pending	npm outdated returns no minor/patch updates; lint, build-storybook, and test all exit 0
1.2	Install react-easy-crop, browser-image-compression, heic2any	front-end-engineer	1.1	Pending	Packages present in package.json; npm ls react-easy-crop resolves without peer warnings
1.3	Move utils.ts, pagination.ts, date-time.ts to src/types/canary/utilities/; update all imports; create barrel index.ts	front-end-engineer	1.2	Pending	No broken imports anywhere in the codebase; all checks (lint, build-storybook, test) exit 0
1.4	Create image-field-config.ts with all eight image-domain types; export from barrel	front-end-engineer	1.3	Pending	All eight types compile without errors; import { ImageFieldConfig } from '../utilities' resolves in a scratch check
1.5	Extract getInitials from item-grid-columns.tsx to utilities/get-initials.ts; update source import; write get-initials.test.ts (8 tests)	front-end-engineer	1.3	Pending	8 tests pass; item-grid-columns.tsx behavior is unchanged; helper exported from barrel
1.6	Create utilities/get-cropped-image.ts (canvas helper); write get-cropped-image.test.ts (5 tests)	front-end-engineer	1.3	Pending	5 tests pass; function exported from barrel
1.7	Add ShadCN primitives: alert-dialog, checkbox, popover, progress, slider, aspect-ratio to primitives/	front-end-engineer	1.2	Pending	Each primitive file imports and renders in a manual smoke test; Storybook build exits 0
1.8	Add error-overlay variant to Badge CVA in badge-base.tsx; write 4 unit tests; add 3 new stories and update Playground + AllVariants	front-end-engineer	1.7	Pending	4 new Badge tests pass; 3 new stories visible in Storybook; lint exits 0
1.9	Verify shimmer animation in Skeleton primitive; if absent, add @keyframes shimmer to globals.css @theme block	front-end-engineer	—	Pending	Skeleton component shows animated shimmer in Storybook; Storybook build exits 0
1.10	Create src/components/canary/__mocks__/image-story-data.ts with all five exports	front-end-engineer	1.4	Pending	File exists; TypeScript compiles it without errors; all five named exports are accessible
1.11	Scaffold all target directories: 7 molecule subdirs, 2 atom subdirs, 1 organism subdir — each with empty index.ts	front-end-engineer	—	Pending	All 10 directories and their index.ts files exist on disk
1.12	Create primitive context stories: skeleton-image.stories.tsx (3 stories), tabs-image.stories.tsx (2 stories), alert-dialog-image.stories.tsx (2 stories)	front-end-engineer	1.7	Pending	7 stories render in Storybook; Storybook build exits 0
1.13	Create utilities/utilities.mdx documenting getInitials and getCroppedImage with prose overview and Canvas embeds	front-end-engineer	1.5, 1.6	Pending	MDX page renders in Storybook without acorn parse errors; Storybook build exits 0

Internal Dependency Graph

Tasks that can begin immediately (no dependencies within this run):

• 1.1 — baseline dependency check; must complete first
• 1.9 — shimmer verification is independent of all other tasks
• 1.11 — directory scaffolding is independent of all other tasks

Tasks that unlock after 1.1:

• 1.2 (install packages) — unblocks 1.3 and 1.7

Tasks that unlock after 1.2:

• 1.3 (move utilities) — unblocks 1.4, 1.5, 1.6
• 1.7 (ShadCN primitives) — unblocks 1.8 and 1.12

Tasks that unlock after 1.3:

• 1.4 (image types) — unblocks 1.10
• 1.5 (getInitials) — can run in parallel with 1.6
• 1.6 (getCroppedImage) — can run in parallel with 1.5

Tasks that unlock after 1.5 and 1.6:

• 1.13 (utilities MDX) — requires both helpers to exist

1.1 → 1.2 → 1.3 → 1.4 → 1.10
                 → 1.5 ──┐
                 → 1.6 ──┴→ 1.13
       1.2 → 1.7 → 1.8
                 → 1.12
1.9 (independent)
1.11 (independent)

Exit Criteria

#	Criterion	Verification Command	Expected Output
1	Lint passes with zero warnings	npm --prefix /Users/jmp/code/arda/image-components-worktrees/run-1 run lint	Exit 0
2	Storybook builds cleanly	npm --prefix /Users/jmp/code/arda/image-components-worktrees/run-1 run build-storybook	Exit 0
3	All unit tests pass	npm --prefix /Users/jmp/code/arda/image-components-worktrees/run-1 run test	Exit 0
4	13 new utility unit tests present and passing	npm --prefix /Users/jmp/code/arda/image-components-worktrees/run-1 run test -- --reporter=verbose 2>&1 | grep -E "(get-initials|get-cropped-image)"	8 getInitials tests + 5 getCroppedImage tests all marked PASS
5	4 new Badge error-overlay tests present and passing	npm --prefix /Users/jmp/code/arda/image-components-worktrees/run-1 run test -- --reporter=verbose 2>&1 | grep -E "badge-base"	4 new tests marked PASS
6	7 primitive context stories render in Storybook build output	Inspect storybook-static/ index for skeleton-image, tabs-image, alert-dialog-image story entries	7 story entries present
7	All utility types exported from barrel	node -e "const u = require('./src/types/canary/utilities'); console.log(Object.keys(u))" (or equivalent TypeScript check)	Keys include ImageFieldConfig, ImageMimeType, ImageInput, ImageUploadResult, CropData, PixelCrop, getInitials, getCroppedImage

Handoff

Artifacts Produced (for subsequent runs)

Artifact	Consumer Run	Path
Utilities directory (types, helpers, barrel)	Runs 2, 3, 4	src/types/canary/utilities/
ImageFieldConfig and related types	Runs 2, 3, 4	src/types/canary/utilities/image-field-config.ts
getInitials helper	Run 2 (Avatar refactor)	src/types/canary/utilities/get-initials.ts
getCroppedImage helper	Run 2 (ImagePreviewEditor)	src/types/canary/utilities/get-cropped-image.ts
alert-dialog primitive	Run 2 (ImageDisplay), Run 4 (ImageUploadDialog)	src/components/canary/primitives/alert-dialog.tsx
checkbox primitive	Run 2 (ImageDropZone)	src/components/canary/primitives/checkbox.tsx
popover primitive	Run 3 (ImageHoverPreview)	src/components/canary/primitives/popover.tsx
progress primitive	Run 2 (ImageDropZone, ImagePreviewEditor)	src/components/canary/primitives/progress.tsx
slider primitive	Run 2 (ImagePreviewEditor)	src/components/canary/primitives/slider.tsx
aspect-ratio primitive	Run 2 (ImageDisplay)	src/components/canary/primitives/aspect-ratio.tsx
Badge error-overlay variant	Run 2 (ImageDisplay)	src/components/canary/atoms/badge/badge-base.tsx
Mock data module	Runs 2, 3, 4	src/components/canary/__mocks__/image-story-data.ts
Scaffolded molecule directories	Runs 2, 3	src/components/canary/molecules/{form,image-display,image-drop-zone,image-preview-editor,image-hover-preview,image-inspector-overlay,image-comparison-layout}/
Scaffolded atom directories	Runs 2, 4	src/components/canary/atoms/grid/image/, src/components/canary/atoms/copyright-acknowledgment/
Scaffolded organism directory	Run 4	src/components/canary/organisms/shared/image-upload-dialog/

---

Copyright: (c) Arda Systems 2025-2026, All rights reserved