Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 47 additions & 0 deletions .github/workflows/pages.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
name: Deploy site to GitHub Pages

# Builds site/ (Vite + prerender) and publishes site/dist to https://byronwall.github.io/srcly/.
# Needs Settings › Pages › Source set to "GitHub Actions".
on:
push:
branches: [main]
paths: [site/**, .github/workflows/pages.yml]
workflow_dispatch:

permissions:
contents: read
pages: write
id-token: write

concurrency:
group: pages
cancel-in-progress: false

jobs:
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
timeout-minutes: 10
defaults:
run:
working-directory: site
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
with:
version: 11.9.0
- uses: actions/setup-node@v4
with:
node-version: 24
cache: pnpm
cache-dependency-path: site/pnpm-lock.yaml
- run: pnpm install --frozen-lockfile
- run: pnpm build
- uses: actions/configure-pages@v5
- uses: actions/upload-pages-artifact@v3
with:
path: site/dist
- id: deployment
uses: actions/deploy-pages@v4
13 changes: 0 additions & 13 deletions site/DEPLOY.md

This file was deleted.

41 changes: 21 additions & 20 deletions site/DESIGN.md
Original file line number Diff line number Diff line change
@@ -1,32 +1,33 @@
# Public site

The public site extends Srcly's light application palette. It serves developers who want to inspect a local codebase or create a report for an agent.
The site serves developers who want to try Srcly on their own code, and readers who want to know how it works.
Its look comes from Srcly itself: the page is drawn like a scan.

## Surface modes
## The scope motif

- Landing: Persuade. Lead with real Srcly views, then give two paths: see the product or use it.
- Guides: Read. Group navigation by the visitor's task, keep the article easy to scan, and link search results to the matching section.
- Screenshot viewer: Experience. Let the captured application view fill the screen. Keep zoom, reset, close, keyboard focus, and native image-link fallback.
- Each landing section is a treemap scope: a 1px frame with a mono header strip (`views/`).
- The strip's right side names the part of Srcly's source that implements the section, with its real LOC and maximum complexity from `src/data/tree.json`, and links to it on GitHub. These numbers are never typed by hand.
- Blocks inside a section share 1px rules like treemap tiles (`.steps`, `.views`, `.workflows`). Do not use floating cards with gaps or shadows.
- The hero is a real treemap of Srcly's own source at the captured revision, with the headline in a label block cut into it.

## Tokens

- Canvas: `#f8fafc`; paper: `#fff`; ink: `#17212e`.
- Body detail: `#526273`; rules: `#dce3ea`.
- Links and actions: `#1769aa`; hover: `#0e548d`.
- Type: Inter for text; IBM Plex Mono for code and measurements.
- Page width: 1160px; hero type: 42–68px; body: 15px.
- Controls have visible focus outlines. Motion respects reduced-motion settings.
- Light follows the app's DESIGN.md (Precision Light Console): canvas `#f4f6f9`, paper `#fff`, ink `#0f172a`, rules `#e2e8f0` and `#cbd5e1`, links `#2563eb`.
- Dark is ink: canvas `#0b1220`, paper `#0f172a`, links `#8ab4ff`. The heat ramp stays the same, so tiles read the same in both themes.
- Heat ramp: Srcly's `TREEMAP_RAMP` (`#bfdbfe` → `#e9eef3` → `#fcd34d` → `#fb923c` → `#f87171`), sampled with the app's Lab interpolation in `src/treemap.tsx`. Use it only for data marks: tiles, swatches, the legend, the logo.
- N/A is gray diagonal hatching, never a ramp color.
- Type: Inter for prose; IBM Plex Mono for paths, numbers, scope names and commands.

## Product proof
## Content rules

- Use screenshots captured from the running application. Keep captions specific to the view and the action it supports.
- The hero uses the repository treemap. The gallery uses the treemap, code inspector, and data-flow views.
- The site must not imply that it scans files or that missing measurements equal zero.
- Do not invent metrics or terminal output to fill space.
- Every claim matches the code. Metric definitions come from the catalog; command output comes from a real run.
- Screenshots come from `scripts/capture.mjs`. Captions name the subject and revision.
- The site must not imply that it scans visitor files, or that a missing measurement is 0.
- "How I built it" is Byron's voice. Keep its first-person claims to what the project page and its posts support.

## Guides
## Docs pages

- Navigation groups: Discover, Use Srcly, and Automate & configure.
- Keep the page title, short summary, and edit link in one compact heading area.
- Search results show matching text and link to a matching section when one exists.
- Screenshot figures can open at full size. Keep the image link usable without JavaScript.
- Keep the page title, summary, and edit link in one heading area.
- Search results show matching text and link to the matching section.
- Screenshot figures open at full size; the image link still works without JavaScript.
38 changes: 25 additions & 13 deletions site/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,24 +15,36 @@ Open the printed development URL with `/srcly/` appended.
The build writes `site/dist/`. Each guide has a complete HTML page, with page metadata and a canonical URL.
The browser adds section-linked guide search, copy buttons, and a full-size screenshot viewer.

Edit the product tour, design notes, and user guides in `src/docs/pages/`.
Keep command examples in sync with `server/app/run.py`.
Add new pages to the navigation in `src/App.tsx` when required.
The build reads page titles and introductions from Markdown for search metadata.
## Content

The site uses its own dependencies and build. It does not ship inside the Python wheel.
Pull requests build the site and run its browser checks. See [DEPLOY.md](DEPLOY.md) to publish the build to GitHub Pages.
- The landing page (`src/Landing.tsx`) is the user guide in one page: install, how to read the treemap, the views, workflows, the command line, a reference, and a short "How I built it".
- The reference tables (`src/Reference.tsx`) read `src/data/catalog.json`, Srcly's own metric catalog. Do not retype metric definitions.
- The longer guides are Markdown in `src/docs/pages/`. Add a new page to the navigation in `src/App.tsx`.
- Keep command examples in sync with `server/app/run.py`.

## Reference and design
## Screenshots and data

Draftably's public site supplied the structure: a product preview, direct setup actions, and searchable task guides.
Srcly keeps its light surfaces, blue links, Inter type, and IBM Plex Mono commands.
Real app screenshots show Srcly inspecting its public source and checked-in fixtures.
Capture provenance is in `public/screenshots/README.md`. The site does not scan visitor files.
The docs have three groups: Discover, Use Srcly, and Automate & configure.
`node scripts/capture.mjs [name,name…]` captures everything from a real Srcly run on Srcly's own source.
It clones this checkout's HEAD to a temporary `srcly` folder, starts the API and client on free ports with a temporary cache, and writes:

- `public/screenshots/*.jpg`: the app at 1440 × 900 CSS pixels, 1.5x.
- `src/data/tree.json`: folder and file LOC and complexity, for the treemaps drawn on the page.
- `src/data/catalog.json`: the metric catalog and 2×2 presets.
- `src/data/cli.json`: real `hotspots` and `explain` output.
- `src/data/meta.json`: the source revision and totals the page cites.

It needs the server venv (`cd server && uv sync`), client `node_modules`, and Google Chrome.
A full run takes about five minutes, most of it the compare shot, which scans two revisions.
Rerun it after a release that changes the UI, and commit the screenshots and data together.

## Deploy

`.github/workflows/pages.yml` builds the site and publishes `site/dist` on every push to `main` that touches `site/`.
Pages must use **Settings › Pages › Source: GitHub Actions**. Run the workflow by hand from the Actions tab to publish without a site change.
Pull requests run `.github/workflows/site.yml`: the build and the browser checks.

## Verification

`pnpm test` runs a browser against the built site under `/srcly/`.
It checks static guide content, local links, images, search anchors, screenshot zoom, copy feedback, and narrow screens.
It checks the landing page, static guide content, local links, images, search anchors, screenshot zoom, copy feedback, and narrow screens.
Keep screenshot evidence under the repository's ignored `tmp/` directory.
2 changes: 2 additions & 0 deletions site/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -14,12 +14,14 @@
"dependencies": {
"@fontsource-variable/inter": "^5.3.0",
"@fontsource/ibm-plex-mono": "^5.3.0",
"d3-hierarchy": "^3.1.3",
"lucide-solid": "^1.49.0",
"marked": "^17.0.6",
"solid-js": "^1.9.18"
},
"devDependencies": {
"@playwright/test": "1.62.0",
"@types/d3-hierarchy": "^3.1.7",
"@types/node": "^24.19.2",
"typescript": "~5.9.3",
"vite": "^7.3.7",
Expand Down
17 changes: 17 additions & 0 deletions site/pnpm-lock.yaml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion site/public/favicon.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
20 changes: 12 additions & 8 deletions site/public/screenshots/README.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,16 @@
# Screenshot assets

These app screenshots come from a real local Srcly run at source revision `653037aa` (2026-11-06). The scanned source is the public `client/src` tree. The graph examples use the checked-in `engine/examples/symbol-graph` fixture. No private repository data appears in these images.
`site/scripts/capture.mjs` writes every JPEG here from a real local Srcly run. Rerun it rather than editing an image.

Each JPEG is 1440 × 960 pixels at quality 88. Capture URLs, UI steps, raw PNG paths, and factual captions are recorded in `tmp/10x/docs/app/CAPTURES.md`.
The current set is Srcly scanning a clone of its own repository at `e4485453` (2026-11-14). The symbols and data-flow shots use the checked-in `engine/examples/symbol-graph` fixture. No private repository data appears in these images.

- `treemap.jpg` — client source tree sized by LOC and colored by maximum complexity.
- `hotspots.jpg` — ranked complexity list beside the treemap.
- `quadrant.jpg` — activity 2×2, with the Hot mess quadrant selected.
- `code-inspector.jpg` — `App.tsx` source and metrics, focused on the `openAt` complexity witness.
- `data-flow.jpg` — route trace with its partial outcome and callback handoff in the inspector.
- `symbols.jpg` — `NotePage` references in the symbol graph.
Each JPEG is 2160 × 1350 pixels: a 1440 × 900 viewport at 1.5x, quality 82.

- `treemap.jpg`: the whole repository, sized by LOC and colored by maximum complexity.
- `hotspots.jpg`: Hot Spots ranking files by complexity beside the treemap.
- `quadrant.jpg`: the Activity 2×2, with the Hot mess quadrant selected.
- `code-inspector.jpg`: `client/src/viz/deps/viewModel.ts`, opened on `buildViewModel`, the repository's most complex function.
- `graph.jpg`: the import graph around `client/src/viz/treemap`.
- `compare.jpg`: compare mode for commit `5a8a9c38` (symbols dead and hub overlays).
- `symbols.jpg`: Symbols mode centered on `NotePage`.
- `data-flow.jpg`: the `/notes/[id]` trace from `NotePage`, with where it stops.
Binary file modified site/public/screenshots/code-inspector.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added site/public/screenshots/compare.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified site/public/screenshots/data-flow.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added site/public/screenshots/graph.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified site/public/screenshots/hotspots.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified site/public/screenshots/quadrant.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified site/public/screenshots/symbols.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified site/public/screenshots/treemap.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Loading