Skip to content

v0.0.1.0 chore: scaffold Hình Học Sống (Astro + GitHub Pages)#1

Merged
tiennm99 merged 7 commits intomainfrom
feat/scaffold
Apr 29, 2026
Merged

v0.0.1.0 chore: scaffold Hình Học Sống (Astro + GitHub Pages)#1
tiennm99 merged 7 commits intomainfrom
feat/scaffold

Conversation

@tiennm99
Copy link
Copy Markdown
Owner

@tiennm99 tiennm99 commented Apr 29, 2026

Summary

Scaffold the Vietnamese THCS geometry visualizer per the /office-hours + /autoplan plan. Ships v0.0.1.0 — Astro shell + landing page + math-engine boundary + CI/CD. No canvas modules yet (those start weekend 2 with góc nội tiếp as the hero module).

Infrastructure & config

  • Astro 5 SSG with base: '/try-gstack/' for GitHub Pages subdirectory hosting
  • TypeScript strict (Astro's strict tsconfig + path alias ~/* → src/*)
  • Tailwind 3 with locked SGK 3-color palette (#D7263D / #1B998B / #F46036)

Vietnamese-first frontend

  • Be Vietnam Pro single family (woff2, weights 400/500/700, vietnamese subset) self-hosted via @fontsource/be-vietnam-pro so KaTeX/CDN-blocking ISPs can't break the page
  • font-feature-settings: "kern", "locl" for proper diacritic positioning; 17px body / 1.6 line-height / max-w-prose 56ch
  • BaseLayout.astro with lang="vi", canonical, OpenGraph (vi_VN), X-Frame-Options: DENY
  • All copy routed through src/i18n/vi.ts + t() from day 1; English ships later by adding en.ts
  • Landing page lists three grade cards (lớp 7 / 8 / 9) with "Sắp ra mắt" badges

Math engine boundary

  • src/geom-engine/vec.ts — pure module, no DOM imports allowed (will be enforced by eslint rule once added). Vec2 with add/sub/scale/dot/len/dist/normalize/approxEqualLen.
  • EPSILON_LEN = 0.5 (viewBox units, ~1.25px @ 1000-unit viewBox) justified vs ~4px human drag precision per autoplan eng review
  • scale() normalizes IEEE-754 -0 back to +0 with + 0 idiom — a subtle invariant that prevents signed-zero ghosts in downstream coordinate comparisons

CI/CD

  • .github/workflows/ci.yml — typecheck + Vitest + build on PRs and pushes to main
  • .github/workflows/deploy.yml — actions/deploy-pages@v4 on push to main, concurrency-grouped so a force-push retry doesn't abort an in-flight rollback

Operational

  • RUNBOOK.md — rollback procedure + the deferred .vn domain trigger thresholds (500 sessions / 30d, 1 organic teacher share, or ≥5 modules shipped)
  • TODOS.md — deferred autoplan items organized by component, P0–P4

⚠️ Pre-merge action required

GitHub Pages must be enabled with Source = GitHub Actions before the deploy workflow will succeed:

  • Repo → Settings → Pages → Source: "GitHub Actions"

The first push to main after merge will then deploy to https://tiennm99.github.io/try-gstack/.

Test Coverage

[+] src/geom-engine/vec.ts   (the only logic module added)
  ├── vec()              [★★★ TESTED] basic + many call-sites
  ├── add()              [★★★ TESTED] commutativity + non-mutation
  ├── sub()              [★★★ TESTED] inverse-of-add
  ├── scale()            [★★★ TESTED] standard + k=0 (signed-zero edge case)
  ├── dot()              [★★★ TESTED] standard + orthogonal
  ├── len()              [★★★ TESTED] (3,4)→5
  ├── dist()             [★★★ TESTED] symmetry + self=0
  ├── normalize()        [★★★ TESTED] unit + zero-vector + direction preservation
  └── approxEqualLen()   [★★★ TESTED] within/outside epsilon + EPSILON_LEN value pin

COVERAGE: 9/9 functions tested (100%)
QUALITY: ★★★:9

Tests: 0 → 16 (+16 new). Vitest config gates src/geom-engine/** at 95% line/function/statement, 90% branch. Property tests via fast-check + e2e via Playwright deferred to first canvas module per autoplan plan.

Pre-Landing Review

1 INFORMATIONAL finding:

  • src/pages/index.astro references import.meta.env.PUBLIC_VERSION ?? '0.0.1.0'. The env var is never set, so the fallback always wins; will rot when VERSION bumps. Filed in TODOS.md as P3 — wire from CI build before next bump.

No critical/high findings. No SQL/auth/LLM trust-boundary concerns (no backend, no LLM, no DB).

Adversarial Review (Claude inline, Codex unavailable)

Checked: IEEE-754 -0 normalization in scale() correctly propagates NaN/Infinity. siteUrl/basePath env reads happen at SSG build time only — no runtime leak. CSP header policy locked in autoplan but not yet wired in <head> (deferred to first canvas module when KaTeX/script-src tightening becomes load-bearing). actions/deploy-pages@v4 requires GH Pages source = Actions in repo settings (flagged above).

Plan Completion (vs ~/.gstack/projects/tiennm99-try-gstack/ design doc)

  • Astro shell with base: '/try-gstack/'
  • Be Vietnam Pro single family + locked typography sizes
  • TypeScript strict + path alias
  • math-engine boundary in src/geom-engine/
  • EPSILON_LEN = 0.5 (justified)
  • i18n from day 1 via src/i18n/vi.ts
  • CI workflow (typecheck + tests + build)
  • GitHub Pages deploy workflow with actions/deploy-pages@v4
  • VERSION 0.0.1.0 (matches package.json)
  • CHANGELOG, RUNBOOK, README rewrite
  • Module 3 (Góc nội tiếp) — deferred to weekend 2 per plan
  • Module 1, Module 2 — deferred to weekends 3 + 4
  • TheoremCanvas primitive — deferred to weekend 1.5 (built once, reused 3×)
  • KaTeX bundling + SSR-render — deferred to first canvas module
  • Playwright e2e + axe a11y + Lighthouse-CI + size-limit gates — deferred to first JS bundle
  • Phase 0 SERP audit + TikTok mock validation — non-code, P0 in TODOS.md

13/22 plan items DONE in this PR; 9 explicitly deferred per the staged 4-weekend rollout.

Documentation

README.md rewritten as the project README. CHANGELOG.md initialized for v0.0.1.0. RUNBOOK.md documents rollback + the .vn domain validation trigger. No further doc sync needed — all three are fresh in this PR.

Test plan

  • bun install && bun run typecheck && bun run test && bun run build all clean locally
  • All 16 Vitest tests pass
  • Astro check: 0 errors, 0 warnings, 0 hints (10 files)
  • dist/ builds to a single page + sitemap-index.xml
  • CI workflow runs on this PR (pending GH Actions kickoff)
  • deploy.yml succeeds on first push to main after merge (requires Pages source = Actions in repo settings)

🤖 Generated with Claude Code

tiennm99 and others added 7 commits April 29, 2026 16:54
@tiennm99 @claude
chore: add gstack skill routing rules to CLAUDE.md
9d33c82 
Append a "## Skill routing" section so future Claude Code sessions in this repo route
each task through the matching gstack skill (e.g., /investigate for bugs, /ship for PRs,
/office-hours for product brainstorming).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@tiennm99 @claude
chore: scaffold Astro 5 + TypeScript strict with base /try-gstack/
ece7a3b 
Initialize the project per the autoplan-locked decisions:
- Astro 5 SSG, output static, base path /try-gstack/ for GitHub Pages subdirectory hosting
- TypeScript strict (Astro's strict tsconfig + path alias ~/* -> src/*)
- @astrojs/sitemap for SEO meta
- bun as the package manager (lockfile committed)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@tiennm99 @claude
feat: Vietnamese landing page with Be Vietnam Pro + i18n stub
d3954e2 
Implement the locked design decisions D2 (typography) and D3 (palette) plus the i18n
discipline from autoplan eng review:
- Be Vietnam Pro single family (woff2, weights 400/500/700, vietnamese subset) self-hosted
  via @fontsource so KaTeX/CDN-blocking ISPs cannot break the page
- font-feature-settings: "kern", "locl" for proper VN diacritic positioning
- 17px body / 1.6 line-height / max-w-prose 56ch (denser than English)
- 3-color SGK-aligned palette in tailwind config: pair1 #D7263D, pair2 #1B998B, pair3 #F46036
- BaseLayout with lang="vi", canonical URL, OpenGraph (vi_VN), X-Frame-Options DENY
- src/i18n/vi.ts holds every user-facing string; t() helper resolves the active locale.
  Adding English later means adding en.ts; no string churn through templates.
- Landing page lists three grade cards with "Sắp ra mắt" status (modules ship later)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@tiennm99 @claude
test: bootstrap Vitest with pure geom-engine vec module
2195476 
Establish the math-engine boundary and test discipline from autoplan eng decision E2:
- src/geom-engine/ is pure (no DOM imports allowed); first module is vec.ts
- Vec2 helpers: vec, add, sub, scale, dot, len, dist, normalize, approxEqualLen
- EPSILON_LEN=0.5 viewBox units justified vs ~4px human drag precision
- scale() normalizes IEEE-754 -0 back to +0 so consumers don't see signed-zero ghosts
- Vitest config gates the module at 95% line/function/statement, 90% branch
- 16 unit tests covering commutativity, mutation safety, orthogonality, normalization,
  and EPSILON tolerance behavior

Property tests via fast-check come with the first canvas module; this commit establishes
the test scaffold so adding them later is one dependency away.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@tiennm99 @claude
ci: GitHub Actions test workflow + Pages deploy via deploy-pages@v4
d5ef5e8 
Wire the autoplan-locked CI/CD pipeline (decision E3) for GitHub Pages hosting:
- ci.yml: typecheck + tests + build on every PR and push to main
- deploy.yml: build + actions/deploy-pages@v4 on push to main, concurrency-grouped
  so a force-push retry doesn't abort an in-flight rollback
- Build env pins SITE_URL=https://tiennm99.github.io and SITE_BASE=/try-gstack so
  astro.config.mjs produces correct canonical/OG URLs against the subdirectory host
- bun 1.3.13 pinned for both workflows

Lighthouse-CI + size-limit gates deferred until the first canvas module ships
(no JS bundle to budget yet — current pages are zero-JS).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@tiennm99 @claude
chore: VERSION 0.0.1.0 + CHANGELOG + RUNBOOK + README rewrite
2f5cee8 
Initial 4-digit gstack version (matches package.json), changelog entry for the scaffold,
operations runbook covering rollback and the deferred .vn domain trigger (500 sessions/30d
OR 1 organic teacher share OR 5+ modules shipped). README rewritten as the project README
for Hình Học Sống with the locked architectural decisions visible to teammates.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@tiennm99 @claude
chore: TODOS.md tracking deferred autoplan items
2bc6ebf 
Capture the deferred work surfaced by the /office-hours + /autoplan reviews so the
backlog is visible to teammates and bisectable from the source-of-truth design doc.
Organized by component (Phase 0 distribution, TheoremCanvas, Module 3/1/2, testing
infrastructure, retention, domain) then priority P0–P4. Per the gstack TODOS.md
format conventions.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@tiennm99 tiennm99 merged commit c538834 into main Apr 29, 2026
1 check passed
@tiennm99 tiennm99 deleted the feat/scaffold branch April 29, 2026 16:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@tiennm99