Skip to content

CLAUDE.md

Latest commit

 

History

History
47 lines (34 loc) · 4.4 KB

CLAUDE.md

File metadata and controls

47 lines (34 loc) · 4.4 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

interscript.org v2 — the Interscript website, rebuilt on Astro 7 (branch astro-migration). It replaces the legacy react-static site that still lives on the main branch — consult main (and TODO.complete/) as the reference for feature parity. Content claims must be factual: do not fabricate partner/authority/endorsement statements.

Commands

npm run dev            # dev server (localhost:4321; bumps port if taken — e2e uses 4322)
npm run build          # static build to dist/
npm run preview        # serve the build

npm run check          # astro check (TypeScript across .astro/.ts/.vue)
npm test               # vitest run (unit tests in test/)
npx vitest run test/site.test.ts   # single test file
npm run test:e2e       # Playwright (e2e/); local runs need `npm run dev` on 4322
npm run lint           # eslint
npm run format         # prettier --write .
npm run generate:catalogue   # regenerate src/data/maps-catalogue.json from .isc sources

Dependency note: interscript-ts is a file: dependency on the sibling checkout ../interscript-ts, and npm run generate:catalogue reads ../maps/maps/*.isc — both sibling repos must exist locally.

Architecture

  • Rendering: Astro output: "static" + @astrojs/node adapter. Pages under src/pages/ are prerendered by default; the real-time routes (src/pages/api/{detect,systems,transliterate,transliterate/batch}.ts) opt out with export const prerender = false and run interscript-ts server-side.
  • Interactive islands: Vue 3 (@astrojs/vue) for tools — MapExplorer, CompareMode, BatchProcessor, DiffViewer, DetectPanel, MarcTool, SubtitlesProcessor, etc. Static pages are plain .astro importing these islands.
  • Map data: ~289 compact .isc maps in public/maps/. The browsable catalogue src/data/maps-catalogue.json is generated by scripts/generate-catalogue.mjs (commit the regenerated file when maps change).
  • Map loading strategies (why two modules): browser runtimes use src/scripts/map-strategies.ts — ISC files first, compiled-JSON HTTP fallback only for .iml libraries (posix, unicode, var-Cyrl, var-kor) which have no ISC form. The SSR API routes use src/lib/server-map-strategies.ts — same order but ISC loads from the filesystem, no HTTP roundtrip. Keep both in sync.
  • Transliteration worker: src/scripts/transliteration-worker.ts runs interscript-ts off the main thread; worker-client.ts is the typed RPC client. Vite bundles the worker via new Worker(new URL(...), { type: "module" }).
  • Design system: single source of truth in src/styles/global.css — Tailwind 4 CSS-first @theme tokens (colors, fonts, type scale, spacing) plus component classes (.btn, .card, .prose, .eyebrow). All pages consume these tokens; don't hardcode hex values. src/layouts/Base.astro owns the header nav / drawer / footer and carries its scoped styles inline.
  • Content: AsciiDoc (src/content/docs/, src/content/blog/) loaded by src/content/loaders/asciidoc.ts (manual frontmatter parse + @asciidoctor/core), rendered into .prose wrappers.
  • Theme: light/dark via data-theme on <html>; tokens flip in src/styles/global.css. A service worker (public/sw.js) provides offline access.

Testing layout

  • test/*.test.ts — vitest + happy-dom; covers pages, components, catalogue integrity, API endpoints.
  • e2e/*.spec.ts — Playwright, Chromium only. In CI the config starts npm run dev itself; locally run the dev server on port 4322 first (config baseURL).

Conventions

  • Conventional Commits (feat:, fix:, docs:, …). All changes go through PRs to main (branch astro-migration is the active migration branch).
  • Lint: eslint.config.mjs (ESLint 10 flat config; TS + Astro + Vue). Prettier: .prettierrc (no semicolons, 100 cols, astro plugin), .prettierignore for generated/legacy paths.
  • Astro whitespace trap: Astro trims the space at a text↔inline-tag line break — Backed by\n<code> renders as byinterscript-ts. prettier-plugin-astro reflows prose and will create such breaks; test/site.test.ts has a guard that fails on them. prettier-ignore comments corrupt .astro files — instead, hand-wrap the paragraph at text-only boundaries and add the file to .prettierignore (see src/pages/compare.astro).