Project Development Requirements (PDR)

GlassesTryON — Open Source Release Pipeline

Generated: 2026-03-22
Repository: https://github.com/estephanobrusa/GlassesTryOn
Version: 1.0.0 (pre-release)

---

Executive Summary

GlassesTryON is a real-time virtual glasses try-on library built on MediaPipe FaceMesh and Three.js. It is structured as a pnpm monorepo with three packages:

• glasses-tryon-core — Framework-agnostic AR engine (camera, face tracking, 3D overlay)
• glasses-tryon-react — <GlassesTryOn> React 18 component wrapping core
• glasses-tryon-demo — Vite development/demo app

The library has a solid technical foundation: well-structured TypeScript, dual ESM/CJS output via tsup, linting/formatting configured, and a reasonable README. However, it is not yet ready for public npm publishing — it lacks tests entirely, has no CI/CD pipeline, is missing all standard open-source community files (LICENSE, CONTRIBUTING, CHANGELOG), has no semantic versioning automation, and both packages are pinned at version 1.0.0 without any release process.

---

Current State Analysis

Architecture

CameraEngine → FaceMeshRunner → FaceGeometryEstimator → PoseApplier → ThreeSceneManager
                                 ↑ CameraCalibration
All orchestrated by GlassesViewer (event emitter pattern)

What EXISTS

Item	Status	Notes
TypeScript source	EXISTS	Strict mode, ES2020 target
Dual ESM/CJS build	EXISTS	tsup with .d.ts generation
ESLint + Prettier	EXISTS	Root-level config covering all packages
Basic README	EXISTS	Architecture, install, usage, roadmap
pnpm monorepo	EXISTS	packages/core, packages/react, packages/demo
Demo app (Vite)	EXISTS	Working local development environment
Git repository	EXISTS	Hosted at github.com/estephanobrusa/GlassesTryOn
Package exports map	EXISTS	exports field in both publishable packages
Source maps	EXISTS	Generated by tsup

What is MISSING or PARTIAL

(Full gap analysis in next section)

---

Gap Analysis

1. Testing Infrastructure

Item	Status	Priority
Test framework setup (Vitest/Jest)	MISSING	P0 — Critical
Unit tests: CameraCalibration	MISSING	P0
Unit tests: FaceGeometryEstimator (pose math)	MISSING	P0
Unit tests: PoseApplier	MISSING	P0
Unit tests: ThreeSceneManager	MISSING	P1
Unit tests: FaceMeshRunner (mocked)	MISSING	P1
Unit tests: GlassesViewer (mocked deps)	MISSING	P1
Unit tests: React <GlassesTryOn> component	MISSING	P1
Integration tests (headless browser)	MISSING	P2
Visual regression tests	MISSING	P3
Test coverage reporting	MISSING	P1
Test coverage thresholds (>80%)	MISSING	P1

Recommended: Vitest (native ESM, fast, monorepo-friendly) + jsdom for DOM APIs + @testing-library/react for component tests. Use vi.mock to stub navigator.mediaDevices and @mediapipe/face_mesh.

2. CI/CD Pipeline

Item	Status	Priority
GitHub Actions workflow directory	MISSING	P0 — Critical
CI: lint + type-check on PR	MISSING	P0
CI: run tests on PR	MISSING	P0
CI: build all packages on PR	MISSING	P0
CD: automated npm publish on release tag	MISSING	P0
CD: changelog generation	MISSING	P1
CD: GitHub Release creation	MISSING	P1
Branch protection rules	MISSING	P1
Matrix testing (Node 18, 20, 22)	MISSING	P2
Demo deployment (GitHub Pages / Vercel)	MISSING	P2
Security scanning (CodeQL / Dependabot)	MISSING	P2
Dependabot configuration	MISSING	P2

Recommended workflow structure:

.github/workflows/
├── ci.yml          # PR checks: lint, typecheck, test, build
├── release.yml     # Tag-triggered: changelog, npm publish, GH release
└── dependabot.yml  # Automated dependency updates

3. NPM Publishing Configuration

Item	Status	Priority
publishConfig in package.json	MISSING	P0 — Critical
.npmignore or files field	MISSING	P0
peerDependencies declared	MISSING	P0
engines field (Node >= 18)	MISSING	P1
repository, bugs, homepage fields	MISSING	P1
keywords for npm discoverability	MISSING	P1
license field in package.json	MISSING	P0
Scoped package names (@org/...) decision	MISSING	P1
react declared as peerDependency in react pkg	MISSING	P0
three declared as peerDependency in core pkg	MISSING	P1
Semantic versioning starting point (0.1.0 vs 1.0.0)	MISSING	P1
npm provenance (via Actions OIDC)	MISSING	P2

Critical fix: glasses-tryon-react lists react as a runtime dependency, not peerDependency. This will cause duplicate React installations in consumer projects.

4. Documentation

Item	Status	Priority
LICENSE file	MISSING	P0 — Critical (required for open source)
CONTRIBUTING.md	MISSING	P1
CHANGELOG.md	MISSING	P1
CODE_OF_CONDUCT.md	MISSING	P2
SECURITY.md	MISSING	P2
API reference docs (TypeDoc)	MISSING	P1
README: badges (npm, CI, license, coverage)	MISSING	P1
README: browser compatibility table	MISSING	P1
README: performance/hardware requirements	MISSING	P2
README: migration guide format	MISSING	P3
JSDoc comments on public API	PARTIAL	P1 — Some exist, not consistent
TypeDoc configuration	MISSING	P2

5. Code Quality Tools

Item	Status	Priority
ESLint configured	EXISTS	—
Prettier configured	EXISTS	—
TypeScript strict mode	EXISTS	—
typecheck script (tsc --noEmit)	MISSING	P0 — No way to verify types without building
lint script at root	EXISTS	—
Pre-commit hooks (husky + lint-staged)	MISSING	P1
Commit message linting (commitlint)	MISSING	P1
Conventional Commits enforcement	MISSING	P1
@typescript-eslint/no-explicit-any rule	PARTIAL	P2 — Several any usages in source
Dead code elimination check	MISSING	P3
Bundle size tracking	MISSING	P2

Note: FaceMeshRunner.ts:14 has private faceMesh: any, GlassesViewer.ts:201 uses any in emit. These should be typed properly.

6. Semantic Versioning & Release Automation

Item	Status	Priority
Conventional Commits format	MISSING	P1
release-please or semantic-release	MISSING	P0 — Critical
Version synchronization across packages	MISSING	P1
Git tags on releases	MISSING	P0
Pre-release (alpha/beta/rc) workflow	MISSING	P2
CHANGELOG.md auto-generation	MISSING	P1

Recommended: release-please (Google) — integrates natively with GitHub Actions, handles monorepos via release-please-config.json, generates conventional changelog, creates GitHub Releases, and triggers npm publish workflow.

7. Security

Item	Status	Priority
Dependabot alerts enabled	MISSING	P1
dependabot.yml config	MISSING	P1
CodeQL analysis	MISSING	P2
SECURITY.md (vulnerability reporting)	MISSING	P2
npm audit in CI	MISSING	P1
Package lock integrity check	PARTIAL	pnpm-lock.yaml exists

8. Examples & Demos

Item	Status	Priority
Local Vite demo app	EXISTS	—
Live hosted demo (GitHub Pages)	MISSING	P2
Vanilla JS/TS example	PARTIAL	In README only, not runnable standalone
React example	PARTIAL	In README only
Vue example	MISSING	P3
Next.js SSR handling example	MISSING	P2 — navigator.mediaDevices is browser-only
CodeSandbox / StackBlitz embed	MISSING	P2

---

Prioritized Roadmap

Phase 1 — Foundation (Release Blockers) — P0 Items

These MUST be done before any public release:

1. Add LICENSE file — MIT recommended (compatible with Three.js MIT and MediaPipe Apache-2.0)
2. Fix peerDependencies — Move react, react-dom to peerDeps in glasses-tryon-react; mark three as peerDep in glasses-tryon-core
3. Add files field to publishable packages (whitelist dist/ only)
4. Add license field to all package.json files
5. Add typecheck script — tsc --noEmit at root covering all packages
6. Setup Vitest — Configure with jsdom, write first unit tests for pure functions
7. GitHub Actions CI — ci.yml: on PR → lint + typecheck + test + build
8. Semantic release — Add release-please config for monorepo
9. GitHub Actions CD — release.yml: on release PR merge → publish to npm

Phase 2 — Quality & Community — P1 Items

10. CONTRIBUTING.md — Development setup, PR guidelines, commit convention
11. CHANGELOG.md — Initial entry for v1.0.0
12. Conventional Commits + commitlint — Enforce on CI
13. Pre-commit hooks — husky + lint-staged for lint/format
14. Test coverage ≥ 80% for core package math functions
15. README badges — npm version, CI status, license, coverage
16. JSDoc on all public API — Consistent documentation
17. repository, bugs, homepage in package.json
18. engines field — { "node": ">=18" }
19. npm audit in CI
20. Dependabot config

Phase 3 — Discovery & Polish — P2+ Items

21. Live demo — Deploy demo to GitHub Pages or Vercel
22. TypeDoc — Auto-generated API docs site
23. CodeQL — Security scanning in CI
24. SECURITY.md — Vulnerability disclosure policy
25. Bundle size CI check
26. Next.js compatibility guide — SSR/dynamic import pattern
27. npm provenance — SLSA Level 3 via OIDC
28. CODE_OF_CONDUCT.md

---

Technical Debt Inventory

Location	Issue	Severity
FaceMeshRunner.ts:14	private faceMesh: any — should type the MediaPipe FaceMesh instance	Medium
GlassesViewer.ts:201	...args: any[] in private emit — use typed event map	Low
ThreeSceneManager.ts:128	Multiple (obj as any) casts — can use typed Three.js traversal	Low
GlassesTryOn.tsx:37	viewerRef.current.start() not awaited in useEffect	Medium
FaceMeshRunner.ts:28	CDN URL hardcoded in source — should be configurable	Medium
All packages	version: "1.0.0" — should be 0.1.0 for pre-stable API	High
packages/react	Missing onFaceLost prop	Low
packages/react	debug: true hardcoded	Medium

---

Package.json Corrections Required (Pre-Publish)

packages/core/package.json

{
  "license": "MIT",
  "engines": { "node": ">=18" },
  "files": ["dist"],
  "peerDependencies": {
    "three": ">=0.150.0"
  },
  "repository": { "type": "git", "url": "https://github.com/estephanobrusa/GlassesTryOn.git" },
  "keywords": ["ar", "virtual-try-on", "glasses", "face-mesh", "mediapipe", "three.js", "webgl"]
}

packages/react/package.json

{
  "license": "MIT",
  "engines": { "node": ">=18" },
  "files": ["dist"],
  "peerDependencies": {
    "react": ">=17.0.0",
    "react-dom": ">=17.0.0"
  },
  "dependencies": {
    "glasses-tryon-core": "workspace:*"
  }
}

(Remove react and react-dom from dependencies)

---

Recommended Tool Choices

Category	Tool	Rationale
Testing	Vitest	Native ESM, fast HMR, Vite-compatible, monorepo support
DOM testing	jsdom + @testing-library/react	Standard, well-supported
Release automation	release-please	GitHub-native, monorepo support, conventional commits
Pre-commit hooks	husky + lint-staged	Industry standard, minimal config
Commit linting	commitlint + @commitlint/config-conventional	Enforces commit format for release-please
API docs	TypeDoc	TypeScript-native, good output quality
CI	GitHub Actions	Already hosting on GitHub, free for public repos
npm publish	npm + OIDC provenance	Most direct path, provenance for supply chain security