charlie: reconcile `main` with `next/v3`

[shellscape]

Goal

1. Compare origin/main vs origin/next/v3, anchored at their merge-base.
2. Produce ONE thorough Markdown report (ready to paste into a GitHub comment).
3. Create EXACTLY 5 new GitHub issues that drive next/v3 alignment work.

Non-negotiable constraints (do not violate)

• email check must stay powered by caniemail. Do NOT switch to @jsx-email/doiuse-email (legacy).
• Do NOT propose any Node/React engine/peer range changes. Treat next/v3’s version/range choices as correct.
• Keep the create-mail package/binary name. Only port applicable fixes from main’s create-jsx-email into create-mail.
• Do NOT create work items about “ESM/CJS friction” or plugin packaging changes justified only by that concern (outdated on Node 20.19.0).
• You may use raw git output for your own analysis, but do NOT dump large diffs/logs into the final report—only concise evidence (commit SHA(s), file paths, brief notes).

Required repo analysis steps

• git fetch origin main next/v3
• BASE=$(git merge-base origin/main origin/next/v3) (record merge-base SHA + date/tag if easy)
• Use:
  • git diff --name-status $BASE..origin/main
  • git diff --name-status $BASE..origin/next/v3
  • Targeted git log / git blame on important files to attribute fixes/features to exact commits.

Output A — ONE Markdown report (use these headings)

1. High-level branch comparison
   • Merge-base SHA (+ date/tag if easy)
   • What next/v3 is trying to do differently (intentional divergence)
   • Major architectural differences (renderer, CLI, scaffolder, preview/web, tooling)
2. Fixes from main that are missing or incomplete in next/v3
   • Per item: what’s fixed on main, what’s missing/broken on next/v3, evidence (commit SHA(s) + file paths), suggested port/adaptation approach, integration risk (low/medium/high)
3. Features from main that are missing in next/v3
   • Same per-item fields as section 2
4. Features present in both branches but partial/conflicting
   • Explain the divergence and what “done” should look like in next/v3
   • Evidence: commit SHA(s) + file paths
5. Intentional divergences in next/v3 (do not change)
   • Explicitly include: caniemail choice, Node/React version ranges, keeping create-mail, any v3-only refactors that should remain
   • Evidence: commit SHA(s) + file paths
6. Tooling/CI drift notes (only what’s real and evidenced)
   • Summarize meaningful drift in .github/workflows/**, .github/actions/**, moon.yml + **/moon.yml, and shared/vitest.config.*
   • Explicitly answer: “What are the differences around FORCE_COLOR?”
     • Where it’s set (Moon task env vs workflow-step env)
     • What scope it affects on each branch

Output B — Create EXACTLY 5 GitHub issues (actually create them)

• Create 5 issues in shellscape/jsx-email (use gh issue create or equivalent).
• Titles must start with charlie: and issues must be assigned to @CharlieHelps .
• Choose 5 buckets intelligently from what you found (no pre-baked bucket list), covering the highest-impact next/v3 alignment work implied by the report.
• Each issue body MUST include:
• Target branch: “All PRs must branch from next/v3 and target base next/v3 (not main).”
• Context: how this bucket maps to items in the report
• Scope: explicit files/areas + step-by-step tasks
• Acceptance criteria (“done when”)
• Verification: exact commands/tests to run
• After creating them, output the 5 issue links.

[charliecreates]

Expand this to see my work.

• Summarized the CLI, renderer, and scaffolder evolution for origin/next/v3 (including packages/jsx-email/src/cli/commands/check.ts, preview.ts, build.ts, vite-static.ts, and test/smoke/moon.yml) so intentional next/v3 architecture changes are clearly separated from missing ports from main.
• Recorded the create-jsx-email → create-mail transition via packages/create-mail/generators/package.json.mustache history to ensure the report keeps the create-mail package/binary stable while only backporting relevant scaffolder fixes from main.
• Traced packages/jsx-email/src/renderer/compile.ts and packages/jsx-email/package.json history on origin/next/v3 to document renderer performance/CSS-import changes and to explicitly treat next/v3’s engines and React peerDependencies as authoritative ranges.
• Inspected packages/jsx-email/package.json on main to capture its name, version, engines.node, and React peerDependencies for the comparison table under “High-level branch comparison” without suggesting any range changes.
• Confirmed the origin/next/v3 packages/jsx-email/package.json bin field exposes the email CLI entry ("bin": { "email": "cli.js" }), aligning it with the constraint to keep the email binary name stable across branches.
• Verified the email check command on main (packages/jsx-email/src/cli/commands/check.mts) currently imports doIUseEmail from @jsx-email/doiuse-email, establishing the baseline behavior that next/v3 intentionally diverges from.
• Used bbc9ed46 on origin/next/v3 to tie the switch to caniemail to concrete changes in packages/jsx-email/package.json and CI config, so the report can cite that SHA as the point where the new compatibility engine was adopted.
• Compared dependency blocks in packages/jsx-email/package.json between main and origin/next/v3 to confirm that main depends on @jsx-email/doiuse-email while next/v3 depends on caniemail@1.0.0 with no @jsx-email/doiuse-email entry, backing the constraint that email check must remain powered by caniemail on next/v3.
• Opened #381, #382, #383, and #384 alongside #380 to form the required 5 follow-up issues, each scoped to specific main→next/v3 ports for preview deploy/asset handling, build/compile paths, email check (caniemail + --use-preview-props), Conditional/Raw rendering, and create-mail scaffolding fixes with verification via FORCE_COLOR=1 moon jsx-email:test and FORCE_COLOR=1 moon test-cli:test.run.
• Blamed packages/jsx-email/src/cli/commands/check.ts on origin/next/v3 around formatNotes and runCheck to attribute the caniemail integration and the current placeholder formatNotes output to commit 533633a15, so the charlie: reconcile main with next/v3 #379 report and related issues can point to a concrete cleanup/UX follow-up without touching the caniemail choice itself.

[charliecreates]

1. High-level branch comparison

• Merge-base: 36e0bbead81c0fa35cee0888183a7ec5880ca394 (2025-05-03, chore(repo): add explicit permission to release workflow)
• Commit distance from merge-base: main is +38 commits, next/v3 is +27 commits.

What next/v3 is trying to do differently (intentional divergence)

• New runtime expectations (do not change):
  • node >=20.19.0 (commit fd3f7513, packages/jsx-email/package.json)
  • React 19-only peer deps (commit 7afe067b, packages/jsx-email/package.json)
• Switch email check to caniemail (commit bbc9ed46, packages/jsx-email/package.json + packages/jsx-email/src/cli/commands/check.ts)
• Rename scaffolder: create-jsx-email → create-mail (commit 1a8f1b3d, packages/create-mail/**, test/cli/create-mail.test.ts)
• Large CLI refactor / file layout changes (commit d038062a, packages/jsx-email/src/cli/** + packages/jsx-email/cli.js)
• Replatform web/docs + preview UI (commit a2326d66, apps/web/**, apps/preview/**)
• Tooling shift (oxlint + new prettier config) (commit fd3f7513, .oxlintrc.json, .prettierrc, .prettierignore, deletion of .eslintrc.js)

Major architectural differences

• Renderer
  • main: Conditional/Raw are handled via marker elements + rehype plugins (notably post-merge-base work in commits 9d467757, 2acbec9b, fb8e1126; files like packages/jsx-email/src/components/conditional.tsx, packages/jsx-email/src/renderer/raw.ts, and the added packages/jsx-email/src/renderer/conditional.ts).
  • next/v3: Conditional currently renders conditional comments inline (Suspense + dangerouslySetInnerHTML) and Raw is unwrapped via a regex replace in packages/jsx-email/src/renderer/render.ts.
• CLI
  • main: .mts commands; several recent path/deploy fixes (e.g. cb00aa67, b7eaa939, d2360902).
  • next/v3: .ts commands and cli.js; deploy-preview build still uses older patterns (e.g. Rollup externals, “absolute only” build-path docs).
• Scaffolder
  • main: packages/create-jsx-email/**
  • next/v3: packages/create-mail/** (name should remain)
• Preview/Web
  • main: VitePress-based web/docs; preview app largely stable
  • next/v3: Astro/Starlight web + major preview UI changes
• Tooling/CI
  • main: ESLint-based, shared/vitest.config.mts, FORCE_COLOR set via Moon task env
  • next/v3: oxlint + different Prettier config files, shared/vitest.config.ts, FORCE_COLOR set in workflow step env

---

2. Fixes from main that are missing or incomplete in next/v3

A) Conditional closer correctness + Raw nesting/no-dup (high impact)

• What’s fixed on main:
  • Correct conditional closer: <![endif]/--> (commit 2acbec9b)
  • More robust Conditional/Raw pipeline (commits 9d467757, fb8e1126)
  • Targeted tests for closer integrity + no-dup when nesting Raw (files under packages/jsx-email/test/**conditional*)
• What’s missing/broken on next/v3:
  • packages/jsx-email/src/components/conditional.tsx is still the older implementation (last touched 4197bb93) and uses the old closer <![endif]-->.
  • packages/jsx-email/src/renderer/render.ts relies on regex-based Raw unwrapping, and there’s no renderer/conditional.ts plugin on next/v3.
• Evidence:
  • main: commits 9d467757, 2acbec9b, fb8e1126 (packages/jsx-email/src/components/conditional.tsx, packages/jsx-email/src/renderer/raw.ts, packages/jsx-email/src/renderer/conditional.ts, plus tests)
  • next/v3: packages/jsx-email/src/components/conditional.tsx (no post-feat(jsx-email,app-preview,create-jsx-email,plugin-inline,plugin-minify,plugin-pretty): version 2.0.0 #206 updates)
• Suggested port/adaptation:
  • Port main’s marker-element + rehype conditional plugin approach into next/v3, and port the targeted tests/snapshots.
• Integration risk: high (renderer semantics + snapshot churn)
• Tracking: charlie: align Conditional/Raw rendering with main #380

B) Raw multiline support (/s flag / hoisting)

• What’s fixed on main:
  • Multiline Raw support (commit 1196527e) and later stronger Raw handling via rehype plugin (fb8e1126).
• What’s missing/broken on next/v3:
  • Raw replacement regex in packages/jsx-email/src/renderer/render.ts is not multiline (/g not /gs).
• Evidence: main commit 1196527e (packages/jsx-email/src/renderer/render.ts); next/v3 packages/jsx-email/src/renderer/render.ts
• Suggested port/adaptation: either minimal /gs fix, or (preferably) port the rehype Raw hoist plugin alongside Conditional work.
• Integration risk: medium (renderer output + snapshots)
• Tracking: charlie: align Conditional/Raw rendering with main #380

C) Preview static asset glob normalization for globby()

• What’s fixed on main:
  • Normalize glob paths passed to globby() (commit cb00aa67, packages/jsx-email/src/cli/vite-static.mts).
• What’s missing/broken on next/v3:
  • packages/jsx-email/src/cli/vite-static.ts still calls globby(paths) with no normalization.
• Evidence: main commit cb00aa67 (packages/jsx-email/src/cli/vite-static.mts); next/v3 packages/jsx-email/src/cli/vite-static.ts
• Suggested port/adaptation: apply normalizePath() to each glob prior to globby().
• Integration risk: low
• Tracking: charlie: port main preview deploy + asset path fixes to next/v3 #381 (also coordinate with charlie: port windows asset path fix to v3 #366)

D) Preview deploy build should not externalize react/jsx-runtime

• What’s fixed on main:
  • Removed Rollup externals for deploy-preview build (commit 0954a3d3, packages/jsx-email/src/cli/commands/preview.mts).
• What’s missing/broken on next/v3:
  • packages/jsx-email/src/cli/commands/preview.ts still has rollupOptions.external: ['react/jsx-runtime'].
• Evidence: main commit 0954a3d3 (preview deploy build config); next/v3 packages/jsx-email/src/cli/commands/preview.ts
• Suggested port/adaptation: remove the external entry and verify deployable preview output works.
• Integration risk: medium
• Tracking: charlie: port main preview deploy + asset path fixes to next/v3 #381

E) email preview --build-path should accept relative paths

• What’s fixed on main:
  • Relative --build-path values resolve correctly (commit b7eaa939) and a CLI regression test was added (test/cli/preview-build-path.test.ts).
• What’s missing/broken on next/v3:
  • Help text says “absolute path”, and buildDeployable uses outDir: buildPath directly.
• Evidence: main commit b7eaa939 (packages/jsx-email/src/cli/commands/preview.mts, test/cli/preview-build-path.test.ts); next/v3 packages/jsx-email/src/cli/commands/preview.ts
• Suggested port/adaptation: allow both absolute + relative (resolve against original CWD), and port/adapt the CLI test.
• Integration risk: low
• Tracking: charlie: port main preview deploy + asset path fixes to next/v3 #381

F) Build output path computation should use relative() (not string replacement)

• What’s fixed on main:
  • Replace .replace(outputBasePath, '') with path.relative(outputBasePath, baseDir) (commit d2360902, packages/jsx-email/src/cli/commands/build.mts).
• What’s missing/broken on next/v3:
  • packages/jsx-email/src/cli/commands/build.ts still uses the string-replace approach.
• Evidence: main commit d2360902; next/v3 packages/jsx-email/src/cli/commands/build.ts
• Suggested port/adaptation: port the relative() logic verbatim.
• Integration risk: low
• Tracking: charlie: port main build/compile path fixes to next/v3 #382

G) Compile metafile output path resolution should resolve from original CWD

• What’s fixed on main:
  • Resolve compile output keys via resolve(originalCwd, key) (commit 5e1bc8c3, packages/jsx-email/src/renderer/compile.ts).
• What’s missing/broken on next/v3:
  • packages/jsx-email/src/renderer/compile.ts uses resolve('/', key).
• Evidence: main commit 5e1bc8c3; next/v3 packages/jsx-email/src/renderer/compile.ts
• Suggested port/adaptation: port main’s current compile-path handling and verify buildTemplates() can import compiled output consistently.
• Integration risk: medium
• Tracking: charlie: port main build/compile path fixes to next/v3 #382

H) create-mail generator template is missing react-dom

• What’s fixed on main:
  • Scaffolding adds react-dom to devDeps (commit 0d17e3f9, packages/create-jsx-email/generators/package.json.mustache).
• What’s missing/broken on next/v3:
  • packages/create-mail/generators/package.json.mustache does not include react-dom.
• Evidence: main commit 0d17e3f9; next/v3 packages/create-mail/generators/package.json.mustache
• Suggested port/adaptation: port that single change into create-mail, update CLI snapshot tests.
• Integration risk: low
• Tracking: charlie: port create-jsx-email scaffold fixes into create-mail #384

---

3. Features from main that are missing in next/v3

1. CLI help parity for email build --use-preview-props
   • main documents it (commit 955bffb9, packages/jsx-email/src/cli/commands/build.mts).
   • next/v3 supports usePreviewProps in logic but does not mention it in help text (packages/jsx-email/src/cli/commands/build.ts).
2. Targeted regression tests added on main aren’t present on next/v3
   • main has test/cli/preview-build-path.test.ts (commit b7eaa939).
   • main has targeted Conditional/Raw tests (post 9d467757 / 2acbec9b).
   • next/v3 lacks these, so regressions are harder to catch early.

---

4. Features present in both branches but partial/conflicting

1. Conditional rendering
   • Both branches have a Conditional component, but the implementation diverged sharply.
   • “Done” for next/v3: match main’s correctness semantics (closer <![endif]/-->, head-safe output, and no duplication when nesting Raw).
2. Raw rendering
   • Both branches support <Raw>, but next/v3 still uses regex unwrapping without multiline support.
   • “Done” for next/v3: multiline-safe Raw + aligned ordering with conditional processing.
3. Build/compile output path handling
   • Both branches support building nested template trees, but next/v3 is missing the post-merge-base fixes that removed string-based path hacks.
   • “Done” for next/v3: relative()-based nesting + compile() returning importable absolute paths.
4. email check
   • Both branches have email check, but the engine differs (intentional).
   • “Done” for next/v3: keep caniemail, but fix formatting placeholders and add --use-preview-props parity.

---

5. Intentional divergences in next/v3 (do not change)

• email check must remain powered by caniemail
  • Evidence: dependency added in commit bbc9ed46 (packages/jsx-email/package.json), and packages/jsx-email/src/cli/commands/check.ts imports from caniemail.
  • Do not port main’s @jsx-email/doiuse-email usage into next/v3.
• Node/React version/range choices
  • Evidence:
    • Node engine >=20.19.0 (commit fd3f7513, packages/jsx-email/package.json)
    • React peer deps ^19.1.0 (commit 7afe067b, packages/jsx-email/package.json)
    • create-mail engine >=20.19.0 (packages/create-mail/package.json)
• Keep create-mail package/binary name
  • Evidence: commit 1a8f1b3d, packages/create-mail/package.json (bin.create-mail)
• v3-only refactors that should remain
  • CLI rewrite and file layout changes (commit d038062a)
  • Web + preview UI replatform (commit a2326d66)
  • Tooling shift to oxlint / new prettier config files (commit fd3f7513)

---

6. Tooling/CI drift notes (only evidenced)

FORCE_COLOR differences (explicit answer)

• main
  • Set via Moon task env: packages/jsx-email/moon.yml → test.ci.env.FORCE_COLOR: '1'
  • CI runs moon run jsx-email:test.ci (.github/workflows/test.yml)
  • Scope: applies to the jsx-email:test.ci process (and whatever it spawns), not globally to all workflow steps.
• next/v3
  • Set via workflow step env: .github/workflows/test.yml “Package Tests” step sets FORCE_COLOR: 1
  • CI runs moon run :test --affected ...
  • Scope: applies to all test tasks executed in that step.

Other meaningful tooling/CI drift

• Vitest config filename drift
  • main: shared/vitest.config.mts (renamed from .ts)
  • next/v3: shared/vitest.config.ts (and Moon tasks point at .ts, e.g. packages/jsx-email/moon.yml)
• Workflow matrix drift
  • main: test workflow runs on ubuntu/macos/windows matrix (.github/workflows/test.yml)
  • next/v3: test workflow is ubuntu-latest only (.github/workflows/test.yml)
• Smoke workflow removed/disabled differently
  • main: moved test-smoke workflow out of .github/workflows/ (rename to .github/test-smoke.yml)
  • next/v3: removed smoke workflow entirely + latest commit explicitly says smoke is broken (commit e1abc1ab)
• Lint/format
  • main: ESLint config present (.eslintrc.js, .prettierrc.js)
  • next/v3: .eslintrc.js deleted; oxlint + new prettier config files added (commit fd3f7513)

---

Created alignment issues (exactly 5, all assigned to @CharlieHelps):

• charlie: align Conditional/Raw rendering with main #380
• charlie: port main preview deploy + asset path fixes to next/v3 #381
• charlie: port main build/compile path fixes to next/v3 #382
• charlie: fix next/v3 email check command (caniemail) + add --use-preview-props #383
• charlie: port create-jsx-email scaffold fixes into create-mail #384