@vib3code/sdk 2.0.1

package/DOCS/DEV_TRACK_SESSION_2026-01-31.md

@@ -0,0 +1,220 @@
+# Dev Track Session — January 31, 2026
+
+**Branch**: `claude/review-project-status-BwVbr`
+**Phase**: E-1 through E-6 (Full Master Plan Execution)
+**Ref**: `DOCS/MASTER_PLAN_2026-01-31.md`
+
+---
+
+## Session Goals
+
+1. Full codebase audit against Phase 5 platform hardening plan
+2. Create Master Plan consolidating all findings
+3. Execute Phase E-1 (Pre-Launch Blockers)
+4. Execute Phases E-2 through E-6 (remaining master plan items)
+
+---
+
+## Commit 1: Master Plan (`2c88aa7`)
+
+- Created `DOCS/MASTER_PLAN_2026-01-31.md` — 570-line master plan with 43 action items across 6 phases
+- Full codebase audit: 570+ files, 95K+ lines
+- Identified 14 broken exports, missing LICENSE, missing CHANGELOG, missing TypeScript barrel
+
+## Commit 2: Phase E-1 Pre-Launch Blockers (`913419f`)
+
+| # | Item | File(s) |
+|---|------|---------|
+| 1 | MIT LICENSE added | `LICENSE` |
+| 2 | 14 broken exports removed | `package.json` — quaternion, pose, sensors, localization, product/telemetry |
+| 3 | TypeScript barrel created | `types/adaptive-sdk.d.ts` |
+| 4 | `npm run dev` alias | `package.json` scripts |
+| 5 | `prepublishOnly` script | `package.json` scripts |
+| 6 | CI publish workflow | `.github/workflows/publish.yml` |
+| 7 | CHANGELOG.md | `CHANGELOG.md` — v1.0.0 + v2.0.0 |
+
+## Commit 3: Phases E-2 through E-6 (this commit)
+
+### E-2: Launch
+
+| Item | File(s) | Notes |
+|------|---------|-------|
+| Landing page | `index.html` | Replaced 3-second meta-refresh with proper landing page: hero, code snippet, feature cards, nav links. Includes `prefers-reduced-motion`. |
+| URL state support | `docs/url-state.js` | Reads/writes params to URL query string. Auto-applies on load. Shareable links. |
+| README update | `README.md` | License badge → MIT. Added Quick Start with `npx @vib3code/sdk init`. Added `build:lib`, `storybook`, `verify:shaders` to dev commands. Updated license section. |
+
+### E-3: Adoption Friction
+
+| Item | File(s) | Notes |
+|------|---------|-------|
+| CLI `init` command | `src/cli/index.js` | `vib3 init my-app` scaffolds package.json + index.html + main.js with VIB3Engine wired up. |
+| React example | `examples/react/index.jsx` + `README.md` | System switching, geometry, hue controls via hooks. |
+| Vanilla JS example | `examples/vanilla/index.html` | Minimal HTML+JS with controls. |
+| Three.js example | `examples/threejs/index.html` | VIB3+ shader on a rotating Three.js cube, imports Three from CDN. |
+| CDN/UMD build | `vite.config.js` | Added `--mode lib` path: produces `dist/lib/vib3.es.js` + `vib3.umd.js`. Added `build:lib` script. |
+| Storybook config | `.storybook/main.js`, `.storybook/preview.js`, `stories/VIB3Engine.stories.js` | html-vite Storybook with dark background, system/geometry/hue/speed/chaos controls. |
+
+### E-4: Quality & Confidence
+
+| Item | File(s) | Notes |
+|------|---------|-------|
+| SpatialInputSystem destroy() | — | Already exists (lines 1726-1752). Audit corrected. |
+| Cross-browser Playwright | `playwright.config.js` | Added Firefox and WebKit (Safari) projects alongside Chromium. |
+| Accessibility CSS | `styles/accessibility.css` | `prefers-reduced-motion`, `focus-visible` outlines, `forced-colors` support, skip-to-content link. |
+
+### E-5: Scale & Distribution
+
+| Item | File(s) | Notes |
+|------|---------|-------|
+| WASM build CI | `.github/workflows/wasm-build.yml` | Triggers on cpp/ changes. Uses Emscripten 3.1.51. Uploads WASM artifacts. |
+| OBS setup guide | `DOCS/OBS_SETUP_GUIDE.md` | 5-step visual guide: start VIB3+, add browser source, enable transparency, position overlay, control parameters. Includes troubleshooting table. |
+
+### E-6: Ecosystem & Community
+
+| Item | File(s) | Notes |
+|------|---------|-------|
+| Bug report template | `.github/ISSUE_TEMPLATE/bug_report.md` | System, browser, OS fields. Repro steps. |
+| Feature request template | `.github/ISSUE_TEMPLATE/feature_request.md` | Area checkboxes for all subsystems. |
+| CONTRIBUTING.md | `CONTRIBUTING.md` | Getting started, dev commands, PR process, code style. |
+| SECURITY.md | `SECURITY.md` | Responsible disclosure to Paul@clearseassolutions.com. Scope covers XSS, GPU exhaustion, WASM safety, MCP validation. |
+| Opt-in error reporter | `src/core/ErrorReporter.js` | `window.onerror` + `unhandledrejection` capture. OFF by default. Rate-limited (50/session). Anonymized. Supports custom callback or HTTP POST. |
+
+---
+
+## Files Changed (All 3 Commits Combined)
+
+### Created (25 files)
+| File | Purpose |
+|------|---------|
+| `DOCS/MASTER_PLAN_2026-01-31.md` | Master plan with 43 items |
+| `DOCS/DEV_TRACK_SESSION_2026-01-31.md` | This session log |
+| `DOCS/OBS_SETUP_GUIDE.md` | OBS integration guide |
+| `LICENSE` | MIT License |
+| `CHANGELOG.md` | v1.0.0 + v2.0.0 release notes |
+| `CONTRIBUTING.md` | Contributor guide |
+| `SECURITY.md` | Security policy |
+| `types/adaptive-sdk.d.ts` | TypeScript barrel re-export |
+| `.github/workflows/publish.yml` | npm publish on Git tag |
+| `.github/workflows/wasm-build.yml` | WASM build CI |
+| `.github/ISSUE_TEMPLATE/bug_report.md` | Bug report template |
+| `.github/ISSUE_TEMPLATE/feature_request.md` | Feature request template |
+| `.storybook/main.js` | Storybook config |
+| `.storybook/preview.js` | Storybook preview |
+| `stories/VIB3Engine.stories.js` | Engine stories |
+| `docs/url-state.js` | URL state manager |
+| `styles/accessibility.css` | Accessibility styles |
+| `src/core/ErrorReporter.js` | Opt-in error telemetry |
+| `examples/react/index.jsx` | React example |
+| `examples/react/README.md` | React example docs |
+| `examples/vanilla/index.html` | Vanilla JS example |
+| `examples/threejs/index.html` | Three.js example |
+
+### Modified (5 files)
+| File | Changes |
+|------|---------|
+| `package.json` | Removed 14 broken exports, license → MIT, added dev/prepublishOnly/build:lib scripts, added LICENSE+CHANGELOG to files |
+| `index.html` | Replaced redirect with landing page |
+| `vite.config.js` | Added library build mode (UMD + ESM) |
+| `playwright.config.js` | Added Firefox + WebKit browser projects |
+| `src/cli/index.js` | Added `init` command for project scaffolding |
+| `README.md` | License badge, Quick Start, dev commands, license section |
+
+---
+
+## Items Requiring Manual / External Action
+
+These items from the master plan cannot be completed in code and need your action:
+
+| Item | Action Required |
+|------|-----------------|
+| npm publish | Configure `NPM_TOKEN` in GitHub repo secrets, push `v2.0.0` tag |
+| Demo videos/GIFs | Screen record 30s of each system, add to `assets/` and README |
+| Figma Community publish | Generate plugin bundle from `FigmaPlugin.js`, publish via Figma Dev Mode |
+| GitHub Discussions | Enable in repo Settings → Features → Discussions |
+| GitHub Projects board | Create in repo → Projects tab |
+| Discord community | Create server externally |
+| Blog posts | Content creation |
+| TypeScript types for v2.0.0 modules | Large effort — 18 `.d.ts` files needed for creative/integrations/advanced |
+| Unit tests for v2.0.0 modules | Large effort — 18 test files needed |
+
+---
+
+## Phase Status
+
+| Phase | Items | Done | Remaining |
+|-------|-------|------|-----------|
+| E-1: Pre-Launch Blockers | 7 | 7 | 0 |
+| E-2: Launch | 5 | 3 | 2 (videos, full demo polish) |
+| E-3: Adoption | 5 | 5 | 0 (Vue/Svelte examples could be added) |
+| E-4: Quality | 9 | 3 | 6 (unit tests, mobile, memory leak, benchmarks) |
+| E-5: Scale | 6 | 2 | 4 (WebGPU primary, canary builds, Figma, Releases) |
+| E-6: Ecosystem | 11 | 4 | 7 (gallery app, tutorial, API docs, community) |
+| **Total** | **43** | **24** | **19** |
+
+---
+
+## Session 2 (continued) — Commits 4-6
+
+### Commit 4: WebGPU Primary Render Path (`c28886c`)
+
+| Item | File(s) | Notes |
+|------|---------|-------|
+| WebGPU as primary render path | `src/core/VIB3Engine.js` | Flipped `preferWebGPU` default from `false` to `true`. Added WebGPU bridge init for all 3 systems (Quantum, Faceted, Holographic) with try/catch and WebGL fallback. |
+
+### Commit 5: TypeScript Types for v2.0.0 Modules (`74a8f43`)
+
+23 files changed, 1620 insertions:
+
+| Module | File(s) | Notes |
+|--------|---------|-------|
+| SpatialInputSystem | `types/reactivity/SpatialInputSystem.d.ts` | 8 source types, 8 axes, full method signatures |
+| Creative (4 files) | `types/creative/*.d.ts` + `index.d.ts` | ColorPresets, TransitionAnimator, PostProcessing, Timeline |
+| Integrations (8 files) | `types/integrations/*.d.ts` + `index.d.ts` | React, Vue, Svelte, Figma, Three.js, TouchDesigner, OBS |
+| Advanced (6 files) | `types/advanced/*.d.ts` + `index.d.ts` | WebXR, WebGPU Compute, MIDI, AI Presets, OffscreenWorker |
+| ErrorReporter | `types/core/ErrorReporter.d.ts` | Error report payload, options |
+| Barrel update | `types/adaptive-sdk.d.ts` | Re-exports all 18 new modules |
+| Engine types fix | `types/core/VIB3Engine.d.ts` | preferWebGPU default → true |
+
+### Commit 6: Examples, Canary CI, and Unit Tests (`61fa5e7`)
+
+18 files changed, 1528 insertions:
+
+| Item | File(s) | Notes |
+|------|---------|-------|
+| Vue 3 example | `examples/vue/index.js` + `README.md` | Composition API pattern with watchers |
+| Svelte example | `examples/svelte/index.js` + `README.md` | onMount/onDestroy lifecycle pattern |
+| Canary builds CI | `.github/workflows/canary.yml` | Publishes `@vib3code/sdk@canary` on every main push |
+| 11 unit test files | `tests/creative/*.test.js`, `tests/advanced/*.test.js`, `tests/integrations/*.test.js`, `tests/reactivity/SpatialInputSystem.test.js`, `tests/core/ErrorReporter.test.js` | 148 tests, all passing |
+| happy-dom | `package.json` | Added as devDependency for vitest environment |
+
+---
+
+## Updated Phase Status
+
+| Phase | Items | Done | Remaining |
+|-------|-------|------|-----------|
+| E-1: Pre-Launch Blockers | 7 | 7 | 0 |
+| E-2: Launch | 5 | 3 | 2 (videos, full demo polish) |
+| E-3: Adoption | 5 | 5 | 0 — Vue + Svelte examples added |
+| E-4: Quality | 9 | 5 | 4 (mobile, memory leak, benchmarks, flaky timing) |
+| E-5: Scale | 6 | 4 | 2 (Figma publish, GitHub Releases) |
+| E-6: Ecosystem | 11 | 4 | 7 (gallery app, tutorial, API docs, community) |
+| **Total** | **43** | **28** | **15** |
+
+---
+
+## Items Still Requiring Manual Action
+
+| Item | Action Required |
+|------|-----------------|
+| npm publish | Configure `NPM_TOKEN` in GitHub repo secrets, push `v2.0.0` tag |
+| Demo videos/GIFs | Screen record 30s of each system, add to `assets/` and README |
+| Figma Community publish | Generate plugin bundle from `FigmaPlugin.js`, publish via Figma Dev Mode |
+| GitHub Discussions | Enable in repo Settings → Features → Discussions |
+| GitHub Projects board | Create in repo → Projects tab |
+| Discord community | Create server externally |
+| Blog posts | Content creation |
+
+---
+
+*Session end — January 31, 2026*

package/DOCS/ENV_SETUP.md

@@ -0,0 +1,189 @@
+# Environment setup (Firebase, gcloud, Flutter, Android, GH CLI)
+
+This doc provides a **copy/paste** bootstrap script to install and configure:
+- Firebase CLI
+- Google Cloud SDK (`gcloud`)
+- Flutter SDK
+- Android SDK (command-line tools)
+- GitHub CLI (`gh`)
+
+> ✅ Intended for Linux environments (Ubuntu/Debian).  
+> ✅ Replace placeholder values for auth and project configuration.
+
+## Placeholders to fill
+- `<YOUR_GH_TOKEN>`: a GitHub personal access token for `gh auth login --with-token`.
+- `<YOUR_GCP_PROJECT_ID>`: the Google Cloud project ID to set in `gcloud config set project`.
+- `<keystore-password>`: the password for the Android signing keystore (release builds only).
+- `<alias>`: the Android key alias inside the keystore (release builds only).
+- `<alias-password>`: the password for the Android key alias (release builds only).
+- `/path/to/keystore.jks`: the path to your Android signing keystore file (release builds only).
+
+### Where do the Android keystore values come from?
+You only need a keystore when you’re **signing a release build** for distribution (Play Store, internal testing, etc.). For local development and emulator/device testing, you **do not** need these values—debug builds are signed automatically.
+
+If you *do* need a release keystore later, you create it yourself (or your team provides one). The values come from the keystore you generate with `keytool`:
+```bash
+keytool -genkeypair \
+  -alias <alias> \
+  -keyalg RSA \
+  -keysize 2048 \
+  -validity 10000 \
+  -keystore /path/to/keystore.jks
+```
+During that prompt, you choose:
+- the **keystore password** (`<keystore-password>`)
+- the **key alias** (`<alias>`)
+- the **alias password** (`<alias-password>`) (can be the same as the keystore password)
+
+### Emulator vs. cloud testing
+- **Android Emulator (local):** best for day-to-day development and smoke testing.
+- **Cloud testing (Firebase Test Lab, etc.):** best for automated device coverage in CI.
+
+This guide includes only the SDK/tooling prerequisites; the sections below outline optional emulator and Test Lab setup.
+
+### Optional: Android emulator setup
+If you want a local emulator for development:
+```bash
+sdkmanager "system-images;android-34;google_apis;x86_64" "emulator"
+avdmanager create avd -n vib3-pixel -k "system-images;android-34;google_apis;x86_64"
+emulator -avd vib3-pixel
+```
+
+### Optional: Firebase Test Lab (cloud testing)
+Enable Test Lab in your GCP project and run a sample instrumentation test:
+```bash
+gcloud services enable testing.googleapis.com
+gcloud firebase test android run \
+  --type instrumentation \
+  --app path/to/app.apk \
+  --test path/to/androidTest.apk \
+  --device model=Pixel2,version=30,locale=en,orientation=portrait
+```
+
+## Project configuration example
+If your project ID is already created, you can set it like this:
+```bash
+gcloud config set project gen-lang-client-0544919502
+```
+
+For full project provisioning (APIs, Firebase initialization, and CI service accounts), see
+[`DOCS/PROJECT_SETUP.md`](DOCS/PROJECT_SETUP.md).
+
+## One-shot setup script
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+# -----------------------------
+# 0) System deps (Linux)
+# -----------------------------
+sudo apt-get update -y
+sudo apt-get install -y \
+  curl wget unzip xz-utils zip jq git \
+  ca-certificates gnupg lsb-release \
+  openjdk-17-jdk
+
+# -----------------------------
+# 1) Node.js + Corepack + pnpm
+# -----------------------------
+# If Node is not installed or you want to pin a version, uncomment:
+# curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+# sudo apt-get install -y nodejs
+
+node -v
+corepack enable
+corepack prepare pnpm@9.4.0 --activate
+pnpm -v
+
+# -----------------------------
+# 2) Firebase CLI
+# -----------------------------
+pnpm add -g firebase-tools@13.12.0
+firebase --version
+
+# -----------------------------
+# 3) Google Cloud SDK (gcloud)
+# -----------------------------
+if ! command -v gcloud >/dev/null 2>&1; then
+  echo "Installing Google Cloud SDK..."
+  curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg \
+    | sudo gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg
+  echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" \
+    | sudo tee /etc/apt/sources.list.d/google-cloud-sdk.list
+  sudo apt-get update -y && sudo apt-get install -y google-cloud-sdk
+fi
+gcloud --version
+
+# -----------------------------
+# 4) GitHub CLI
+# -----------------------------
+if ! command -v gh >/dev/null 2>&1; then
+  echo "Installing GitHub CLI..."
+  type -p curl >/dev/null || sudo apt-get install -y curl
+  curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
+    | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
+  sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg
+  echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
+    | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
+  sudo apt-get update -y && sudo apt-get install -y gh
+fi
+gh --version
+
+# -----------------------------
+# 5) Flutter + Android SDK
+# -----------------------------
+FLUTTER_VERSION="3.22.3"
+FLUTTER_DIR="$HOME/flutter"
+if [ ! -d "$FLUTTER_DIR" ]; then
+  echo "Installing Flutter ${FLUTTER_VERSION}..."
+  curl -L "https://storage.googleapis.com/flutter_infra_release/releases/stable/linux/flutter_linux_${FLUTTER_VERSION}-stable.tar.xz" -o /tmp/flutter.tar.xz
+  tar -xf /tmp/flutter.tar.xz -C "$HOME"
+fi
+export PATH="$FLUTTER_DIR/bin:$PATH"
+flutter --version
+
+ANDROID_HOME="$HOME/Android/Sdk"
+ANDROID_CMDLINE="$ANDROID_HOME/cmdline-tools"
+mkdir -p "$ANDROID_CMDLINE"
+if [ ! -d "$ANDROID_CMDLINE/latest" ]; then
+  echo "Installing Android cmdline-tools..."
+  mkdir -p "$ANDROID_CMDLINE/latest"
+  curl -L "https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip" -o /tmp/cmdline-tools.zip
+  unzip -q /tmp/cmdline-tools.zip -d /tmp/cmdline-tools
+  mv /tmp/cmdline-tools/cmdline-tools/* "$ANDROID_CMDLINE/latest"
+fi
+export PATH="$ANDROID_CMDLINE/latest/bin:$ANDROID_HOME/platform-tools:$PATH"
+
+yes | sdkmanager --licenses
+sdkmanager "platform-tools" "platforms;android-34" "build-tools;34.0.0"
+
+# -----------------------------
+# 6) Project deps
+# -----------------------------
+pnpm install
+
+# -----------------------------
+# 7) Auth placeholders (fill in)
+# -----------------------------
+# --- GitHub CLI ---
+# gh auth login --with-token <<'EOF'
+# <YOUR_GH_TOKEN>
+# EOF
+
+# --- Firebase ---
+# firebase login:ci --no-localhost
+# firebase use --add
+
+# --- GCloud ---
+# gcloud auth login --no-launch-browser
+# gcloud auth application-default login --no-launch-browser
+# gcloud config set project <YOUR_GCP_PROJECT_ID>
+
+# --- Android signing (if needed) ---
+# export ANDROID_KEYSTORE_PATH="/path/to/keystore.jks"
+# export ANDROID_KEYSTORE_PASSWORD="<keystore-password>"
+# export ANDROID_KEY_ALIAS="<alias>"
+# export ANDROID_KEY_PASSWORD="<alias-password>"
+
+echo "✅ Setup complete"
+```