Loading...
Loading...
Loading...
# 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`
```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`
```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 |
A standalone type stub package for spotipy using Pydantic models generated from the official Spotify Web API OpenAPI schema.
This project provides a comprehensive LLM pricing comparison website with:
<laravel-boost-guidelines>