Merge pull request #60 from TwilioDevEd/feat/DEVED-13514-restore-char-detail-view

feat: Restore per-character detail view with UCS-2 highlighting

Author: thinkingserious

.claude/settings.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      
+    ]
+  }
+}

.github/workflows/test.js.yml

@@ -11,8 +11,9 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [14.x, 16.x, 18.x, 19.x]
+        node-version: [20.x, 22.x]
         # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
+        # Node 14/16/18 removed — EOL; lint-staged@16 requires >=20.17
 
     steps:
     - uses: actions/checkout@v3

.gitignore

@@ -38,4 +38,11 @@ typings/
 .DS_Store
 
 # Context files (not for commits)
-.context/
+.context/
+
+# Claude Code user-specific settings
+.claude/settings.local.json
+
+# Playwright
+tests/e2e/results/
+tests/e2e/reports/

.husky/pre-commit

@@ -0,0 +1 @@
+npx lint-staged

AGENTS.md

@@ -0,0 +1,98 @@
+# AGENTS.md — AI Agent Guidelines for Message Segment Calculator
+
+This file provides universal guidelines for any AI agent (Claude Code, Codex, GitHub Copilot, or custom) working in this repository.
+
+## Context Loading Protocol
+
+Before starting any work:
+
+1. Read `CLAUDE.md` for repo structure, conventions, and workflow
+2. Read this file for development workflow and review process
+3. Check `docs/pr-reviews/README.md` for the PR review process
+
+## Development Workflow
+
+```
+PLAN -> JIRA -> BRANCH -> CODE -> TESTS -> PR -> REVIEW
+```
+
+1. **Plan**: Present a 3-7 bullet checklist before coding
+2. **JIRA**: Create or update a JIRA ticket using `createJiraService()` from `~/Projects/deved-agents/src/services/jira-service.js`
+3. **Branch**: Create branch as `{type}/{TICKET-KEY}-{description}`
+4. **Code**: Follow conventions in `CLAUDE.md`
+5. **Tests**: Run `npm run check` (lint + test), ensure all pass
+6. **PR**: Create PR with JIRA ticket key in description
+7. **Review**: Follow 3-agent + 1-human pattern (see below)
+
+## PR Review Process
+
+Every PR gets reviewed by 3 AI agents + 1 human:
+
+| Reviewer | Focus | Template |
+|----------|-------|----------|
+| Claude Code | Architecture, quality, test coverage | `docs/pr-reviews/<ID>/claude.md` |
+| Codex | Correctness, security, edge cases | `docs/pr-reviews/<ID>/codex.md` |
+| GitHub Copilot | Inline suggestions, style | `docs/pr-reviews/<ID>/copilot.md` |
+| Human | Business logic, acceptance criteria | `docs/pr-reviews/<ID>/human.md` |
+
+Create review scaffold: `mkdir docs/pr-reviews/<PR-number>` and add template files.
+
+See `docs/pr-reviews/README.md` for the full review template and process.
+
+## Security Gates
+
+Before committing, verify:
+
+- [ ] No secrets in code (API keys, tokens, passwords)
+- [ ] `.env` file is not staged
+- [ ] `.claude/settings.local.json` is not staged (gitignored)
+- [ ] No hardcoded credentials — use environment variables
+
+## Quality Gates
+
+Before creating a PR:
+
+- [ ] `npm run check` passes (lint + test)
+- [ ] `npm run release` builds successfully
+- [ ] New UI uses CSS variables from `tokens.css`, not hard-coded colors
+- [ ] Interactive elements have `tabindex`, `role`, and `aria-label`
+- [ ] Both `dist/` and `docs/scripts/` built artifacts are committed
+
+## JIRA Integration
+
+DevEd JIRA is at `twilio-productivity.atlassian.net`, project `DEVED`.
+
+Programmatic access uses `~/Projects/deved-agents/src/services/jira-service.js`:
+
+```javascript
+import { createJiraService } from '~/Projects/deved-agents/src/services/jira-service.js';
+const jira = await createJiraService();
+const ticket = await jira.createTicket({
+  summary: 'Messaging: Short description',
+  description: 'Markdown description (auto-converted to ADF)',
+  issueType: 'Task',
+  component: 'DevEd Internal',
+  storyPoints: 2,
+});
+```
+
+Conventions:
+- Story points: 1, 2, 3, 5 (if 5+, consider breaking into an Epic)
+- Required: acceptance criteria on every ticket
+- Include JIRA key in branch name and PR description for auto-linking
+
+## File Naming Conventions
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Library modules | PascalCase | `SegmentedMessage.ts` |
+| Browser modules | camelCase | `segmenter.ts`, `renderer.ts` |
+| Test files | camelCase + `.test.js` | `segments.test.js` |
+| CSS files | kebab-case | `tokens.css`, `components.css` |
+| PR review docs | `docs/pr-reviews/<PR#>/<reviewer>.md` | `docs/pr-reviews/60/claude.md` |
+
+## Error Handling
+
+- Library code (`src/libs/`) throws on invalid input (e.g., GSM-7 encoding with Unicode chars)
+- Browser code (`src/browser/`) catches errors and renders user-friendly messages
+- The `sms-error` element in `index.html` displays encoding errors gracefully

CLAUDE.md

@@ -0,0 +1,150 @@
+# CLAUDE.md — Message Segment Calculator
+
+You are a coding assistant working on Twilio's Message Segment Calculator, a TypeScript library and browser tool that helps customers understand how SMS and RCS messages are segmented and encoded.
+
+## Quick Reference
+
+```bash
+npm install              # Install dependencies
+npm test                 # Type-check (tsc) + run tests (jest)
+npm run lint             # ESLint on src/**/*.ts
+npm run lint:fix         # ESLint with auto-fix
+npm run check            # Lint + test (mirrors CI)
+npm run release          # Type-check + webpack build (outputs to docs/scripts/)
+npm run build            # Type-check only (tsc)
+npm run test:e2e         # Playwright e2e tests (serves docs/ locally)
+npm run test:e2e:ui      # Playwright interactive UI mode
+```
+
+## Project Structure
+
+```
+src/
+  libs/                  # Core library (encoding, segmentation)
+    SegmentedMessage.ts  # SMS segmentation logic (GSM-7 / UCS-2)
+    RcsSegmentedMessage.ts # RCS segmentation logic (UTF-8)
+    EncodedChar.ts       # Single character with encoding info (isGSM7, codeUnits)
+    Segment.ts           # Segment container (extends Array)
+    UserDataHeader.ts    # UDH for multi-segment messages
+    UnicodeToGSM.ts      # GSM-7 character mapping table
+    SmartEncodingMap.ts  # Twilio Smart Encoding replacements
+    textUtils.ts         # Grapheme splitting utilities
+  browser/               # Browser UI modules
+    main.ts              # Entry point, DOM wiring, event listeners
+    segmenter.ts         # Analysis functions (analyzeSms, analyzeRcs)
+    renderer.ts          # DOM rendering (segment tape, char detail, stats)
+    types.ts             # Shared type definitions (SmsAnalysis, RcsAnalysis, etc.)
+    global.ts            # Library exports for global scope
+  index.ts               # NPM package entry point
+docs/                    # GitHub Pages site
+  index.html             # Main page
+  scripts/               # Built JS bundles (from webpack)
+  styles/                # CSS (tokens.css, layout.css, components.css, animations.css)
+  pr-reviews/            # 3-agent + 1-human PR review docs
+tests/                   # Test suites
+  *.test.js              # Jest unit tests
+  e2e/                   # Playwright e2e tests (char-detail.spec.ts, etc.)
+dist/                    # Built library output (tsc)
+```
+
+## Key Architecture Concepts
+
+### SMS Encoding
+
+- **GSM-7**: 7-bit encoding, 160 chars/segment (153 if multi-segment due to UDH)
+- **UCS-2**: 16-bit Unicode, 70 chars/segment (67 if multi-segment)
+- A single non-GSM character forces the entire message to UCS-2
+- `EncodedChar.isGSM7` identifies whether a character is in the GSM-7 set
+- `EncodedChar.codeUnits` gives the hex code units for any character
+
+### RCS Encoding
+
+- Always UTF-8
+- US: billed per 160-byte "Rich" segment
+- International: "Basic" (<=160 bytes) or "Single" (>160 bytes), no segmentation
+
+### Browser UI Architecture
+
+Data flows through three layers:
+1. **segmenter.ts** — `analyzeSms()` / `analyzeRcs()` produce typed analysis objects
+2. **types.ts** — `SmsAnalysis`, `RcsAnalysis`, `CharDetail`, `SegmentData` interfaces
+3. **renderer.ts** — Pure DOM rendering functions consume analysis objects and render to target elements
+
+### Design System
+
+- Dark theme using CSS custom properties in `docs/styles/tokens.css`
+- Font stack: Plus Jakarta Sans (display), DM Sans (body), JetBrains Mono (code)
+- All colors must use CSS variables from tokens.css, never hard-coded hex values
+- Segment palette: `--color-seg-N-bg` / `--color-seg-N-fg` (5 rotating colors)
+
+## Code Conventions
+
+- TypeScript throughout `src/`, compiled with `tsc`
+- ESLint with `eslint-config-twilio-ts` (includes prettier)
+- Named exports preferred over default exports for browser modules
+- Default exports used in core library (EncodedChar, Segment, etc.) — legacy pattern
+- `npm run lint` must pass with zero errors before committing (warnings are OK for pre-existing issues)
+- Accessibility: interactive elements need `tabindex`, `role`, and `aria-label`
+
+## CI Pipeline
+
+GitHub Actions runs on every PR to `main` (`.github/workflows/test.js.yml`):
+1. `npm install`
+2. `npm run lint` — ESLint (prettier + twilio-ts rules)
+3. `npm test` — tsc + jest
+
+Matrix: Node 20.x, 22.x
+
+Run `npm run check` locally to mirror CI before pushing.
+
+## Pre-commit Hook
+
+Husky + lint-staged runs `eslint --fix` on staged `src/**/*.ts` files at commit time.
+
+## JIRA Conventions
+
+- **Project**: DEVED on `twilio-productivity.atlassian.net`
+- **Component**: "DevEd Internal" for docs projects
+- **Branch naming**: `{type}/{TICKET-KEY}-{description}` (e.g., `feat/DEVED-13514-restore-char-detail-view`)
+- **PR auto-close**: Include JIRA ticket key in PR description
+- **Story points**: 1 (1-4 hrs), 2 (1-2 days), 3 (2-3 days), 5 (3-5 days)
+- **JIRA tooling**: Use `createJiraService()` from the deved-agents repo for programmatic ticket creation
+
+## PR Workflow
+
+1. Create branch from `main` with JIRA ticket key
+2. Implement, run `npm run check` locally
+3. Push and create PR with JIRA link in description
+4. Follow 3-agent + 1-human review (see `docs/pr-reviews/README.md`)
+5. Address review feedback
+6. Squash and merge
+
+## E2E Testing (Playwright)
+
+Tests live in `tests/e2e/` and run against the built `docs/` site:
+- Config: `playwright.config.ts` — auto-serves `docs/` on port 8080
+- Results/reports: `tests/e2e/results/` and `tests/e2e/reports/` (gitignored)
+- `tsconfig.json` includes only `src/`; `jest` ignores `tests/e2e/` — this prevents tsc and Jest from picking up Playwright files
+
+Best practices:
+- Use semantic selectors (`#sms-char-detail`, `.char-block`) and Playwright's auto-waiting
+- Check attributes directly (`toHaveAttribute('hidden', '')`) when `toBeHidden()` doesn't work for elements inside open `<details>`
+- Run `npm run release` before e2e tests to ensure `docs/scripts/` bundles are current
+- Always rebuild dist/docs artifacts before committing changes to `src/browser/`
+
+## Codex CLI Review
+
+Run `codex review --base main` for automated code review. For re-reviews after changes:
+```bash
+codex review --base main --title "PR title here"
+```
+Capture findings in `docs/pr-reviews/<PR>/codex.md`. Mark issues as `[x]` when fixed and note which commit resolved them.
+
+## Common Pitfalls
+
+- `Segment` extends `Array` — iterating with `for...of` works but items include `UserDataHeader` entries. Filter with `isReservedChar` to get only user characters.
+- `EncodedChar.codeUnits` contains GSM-7 septet values for GSM characters, even in UCS-2 messages. When displaying code units for UCS-2 messages, derive UTF-16 values from `raw.charCodeAt()` instead.
+- `EncodedChar.isGSM7` indicates whether a character is in the GSM-7 character set, NOT the message encoding. Use `SegmentedMessage.encodingName` for the actual message encoding.
+- The `docs/scripts/` JS bundles are built artifacts from webpack — always run `npm run release` after changing `src/browser/` files.
+- `dist/` contains tsc output for the NPM package — also rebuilt by `npm run release`.
+- Both `docs/scripts/` and `dist/` should be committed (they are deployed artifacts).

CONTRIBUTING.md

@@ -1,3 +1,80 @@
-# Contributing to Twilio
+# Contributing to Message Segment Calculator
 
 All third party contributors acknowledge that any contributions they provide will be made under the same open source license that the open source project is provided under.
+
+## Quick Start
+
+```bash
+git clone https://github.com/TwilioDevEd/message-segment-calculator.git
+cd message-segment-calculator
+npm install
+npm run check    # Lint + test (mirrors CI)
+```
+
+## Development
+
+```bash
+npm test         # Type-check + jest (659 tests)
+npm run lint     # ESLint on src/**/*.ts
+npm run check    # Lint + test (run before pushing)
+npm run release  # Build library (dist/) + browser bundle (docs/scripts/)
+npm run dev      # Watch mode for tsc
+```
+
+### Local Preview
+
+```bash
+npm run release
+python3 -m http.server 8080 --directory docs
+# Open http://localhost:8080
+```
+
+## Project Layout
+
+- `src/libs/` — Core library: SMS/RCS encoding and segmentation logic
+- `src/browser/` — Browser UI: analysis, rendering, DOM wiring
+- `docs/` — GitHub Pages site (HTML, CSS, built JS bundles)
+- `tests/` — Jest test suites
+- `dist/` — Built NPM package output (tsc)
+
+See `CLAUDE.md` for detailed architecture documentation.
+
+## Making Changes
+
+1. Create a feature branch: `git checkout -b feat/DEVED-XXXXX-description`
+2. Make your changes in `src/`
+3. Run `npm run check` to verify lint + tests pass
+4. Run `npm run release` to rebuild `dist/` and `docs/scripts/`
+5. Commit all changes including built artifacts
+6. Push and create a PR against `main`
+
+### Pre-commit Hook
+
+Husky + lint-staged automatically runs `eslint --fix` on staged TypeScript files at commit time. If lint fails, the commit is blocked — fix the issues and try again.
+
+### CI Pipeline
+
+GitHub Actions runs on every PR to `main`:
+1. `npm run lint`
+2. `npm test`
+
+Across Node.js 14.x, 16.x, 18.x, 19.x. Run `npm run check` locally to catch failures before pushing.
+
+## Code Style
+
+- TypeScript with `eslint-config-twilio-ts` (includes prettier)
+- CSS uses design tokens from `docs/styles/tokens.css` — never hard-code hex colors
+- Interactive UI elements need accessibility attributes (`tabindex`, `role`, `aria-label`)
+
+## PR Review Process
+
+PRs follow a 3-agent + 1-human review pattern:
+
+| Reviewer | Focus |
+|----------|-------|
+| Claude Code | Architecture, quality, test coverage |
+| Codex | Correctness, security, edge cases |
+| GitHub Copilot | Inline suggestions, style |
+| Human | Business logic, acceptance criteria |
+
+See `docs/pr-reviews/README.md` for the full process and templates.