feat: server entry and web shell with design tokens

Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
Lucas Winther
2026-10-30 03:05:49 +01:00
co-authored by Claude Opus 5.5
parent 7f33169487
commit 05eee4cd40
13 changed files with 321 additions and 0 deletions
+44
View File
@@ -0,0 +1,44 @@
import type { AppConfig, AuthService, Feature, JobHandler, ServerContext } from "@stc/contracts";
import { createApp, createJobQueue, loadConfig } from "@stc/core";
import { createCourseRepository } from "@stc/course-format";
import { connect, migrate } from "@stc/db";
import indexHtml from "../../web/index.html";
// Temporary: the learner package replaces this with real sessions.
const anonymousAuth: AuthService = { userFromRequest: async () => null };
export async function startServer(
config: AppConfig,
features: Feature[],
_webFeatures?: unknown,
): Promise<{ server: Bun.Server<undefined>; stop(): Promise<void> }> {
const db = await connect(config.databaseUrl);
await migrate(db);
const courses = await createCourseRepository(config.courseDirs);
const handlers: Record<string, JobHandler> = {};
for (const f of features) Object.assign(handlers, f.jobs);
const jobs = createJobQueue(db, handlers);
const ctx: ServerContext = { config, db, courses, jobs, auth: anonymousAuth };
const app = createApp(ctx, features);
jobs.start();
const server = Bun.serve({
port: config.port,
// Bun routes win over fetch; "/api/*" falls through to the composed app (404 for unknown API paths).
routes: { ...app.routes, "/api/*": (req) => app.fetch(req), "/*": indexHtml },
fetch: (req) => app.fetch(req),
});
return {
server,
async stop() {
await server.stop(true);
await jobs.stop();
await db.close();
},
};
}
if (import.meta.main) {
const config = loadConfig();
const { server } = await startServer(config, []);
console.log(`STCourses listening on ${server.url}`);
}
+36
View File
@@ -0,0 +1,36 @@
import { afterAll, beforeAll, expect, test } from "bun:test";
import { resolve } from "node:path";
import { loadConfig } from "@stc/core";
import { startServer } from "../src/main";
let s: Awaited<ReturnType<typeof startServer>>;
let base: string;
beforeAll(async () => {
const config = loadConfig({
STC_PORT: "0", STC_DATABASE_URL: "sqlite://:memory:", STC_SECRET: "t",
STC_COURSE_DIRS: resolve(import.meta.dir, "../../../fixtures/courses"),
});
s = await startServer(config, []);
base = s.server.url.toString().replace(/\/$/, "");
});
afterAll(() => s.stop());
test("health reports the fixture course", async () => {
expect(await (await fetch(`${base}/api/health`)).json()).toEqual({ ok: true, courses: 1, db: "sqlite" });
});
test("SPA paths return the HTML shell", async () => {
const r = await fetch(`${base}/some/spa/path`);
expect(r.status).toBe(200);
expect(await r.text()).toContain('<div id="root">');
});
test("unknown API paths are 404, not the SPA", async () => {
expect((await fetch(`${base}/api/nope`)).status).toBe(404);
});
test("media honours Range", async () => {
const r = await fetch(`${base}/api/media/sample/media/clip.mp4`, { headers: { Range: "bytes=0-9" } });
expect(r.status).toBe(206);
expect((await r.arrayBuffer()).byteLength).toBe(10);
});
+14
View File
@@ -0,0 +1,14 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>STCourses</title>
<link rel="stylesheet" href="../../packages/ui/src/fonts.css">
<link rel="stylesheet" href="../../packages/ui/src/tokens.css">
</head>
<body>
<div id="root"></div>
<script type="module" src="./src/main.tsx"></script>
</body>
</html>
+4
View File
@@ -0,0 +1,4 @@
import type { WebFeature } from "@stc/contracts";
// Phase 1 packages append one import line each and push into this list.
export const webFeatures: WebFeature[] = [];
+39
View File
@@ -0,0 +1,39 @@
import { createRoot } from "react-dom/client";
import { lazy, Suspense } from "react";
import { createBrowserRouter, Link, Outlet, RouterProvider, type RouteObject } from "react-router-dom";
import { AppShell } from "@stc/ui";
import { webFeatures } from "./features";
function Home() {
return <p className="work">No features installed yet</p>;
}
function Layout() {
const nav = webFeatures.flatMap((f) => f.routes.filter((r) => r.nav?.area === "header"));
const header = (
<>
<Link to="/" style={{ fontWeight: 600, color: "var(--head)", textDecoration: "none" }}>STCourses</Link>
<nav style={{ display: "flex", gap: 14 }}>
{nav.map((r) => <Link key={r.path} to={r.path}>{r.nav!.label}</Link>)}
</nav>
</>
);
return (
<AppShell header={header}>
<Suspense fallback={null}><Outlet /></Suspense>
</AppShell>
);
}
const featureRoutes: RouteObject[] = webFeatures.flatMap((f) =>
f.routes.map((r) => {
const Element = lazy(r.element);
return { path: r.path, element: <Element /> };
}),
);
const router = createBrowserRouter([
{ element: <Layout />, children: [...featureRoutes, ...(featureRoutes.some((r) => r.path === "/") ? [] : [{ path: "*", element: <Home /> }])] },
]);
createRoot(document.getElementById("root")!).render(<RouterProvider router={router} />);
+29
View File
@@ -4,8 +4,17 @@
"workspaces": {
"": {
"name": "stcourses",
"dependencies": {
"@fontsource/ibm-plex-mono": "^5.3.0",
"@fontsource/ibm-plex-sans": "^5.3.0",
"@fontsource/literata": "^5.3.0",
"react": "^19.3.1",
"react-dom": "^19.3.1",
"react-router-dom": "6",
},
"devDependencies": {
"@types/react": "^19",
"@types/react-dom": "^19.3.0",
"bun-types": "^1.3.14",
"typescript": "^5",
},
@@ -59,6 +68,14 @@
},
},
"packages": {
"@fontsource/ibm-plex-mono": ["@fontsource/[email protected]", "", {}, "sha512-eTgnZjZEGk1QtD3ZstF+Vclo2HLAni8YMy34/DxllwZvyz1lR/1RF/xTiAquOBO7MvqBx8D2Ig2WCPMVfdZu7Q=="],
"@fontsource/ibm-plex-sans": ["@fontsource/[email protected]", "", {}, "sha512-CbE4CbbEEZJX860XyUiRpsksXIQR8Rp2XDva2VO53NJox9tVNtusrysd2x5YkUEY3ErQ66W1IiiQL8/wihhw5w=="],
"@fontsource/literata": ["@fontsource/[email protected]", "", {}, "sha512-9JGMT5+YfBK49thoMq9ASaMRJErHT4V4QuMhAEwKHRLreOsIMP2xP6ZRLhPJ0e6YlET+kjWTJuN7LAxt9/gWGQ=="],
"@remix-run/router": ["@remix-run/[email protected]", "", {}, "sha512-q7j5geK7xs3UJSdm9/iytUNclBnLmYx1EnSeCFXHPeutdqgIMeFeHtUZgS3EhlKxdBEAu8OwtJCwmLrEzpSs7Q=="],
"@stc/contracts": ["@stc/contracts@workspace:packages/contracts"],
"@stc/core": ["@stc/core@workspace:packages/core"],
@@ -85,10 +102,22 @@
"@types/react": ["@types/[email protected]", "", { "dependencies": { "csstype": "^3.2.2" } }, "sha512-N0rFCuH9YoxG9/m61l9MfpJKfmLOVU0em7ipIz6TRgSSkvReLB9vL85GB+yr8Bs5leqpvg96JSwF4ZS1s4viQg=="],
"@types/react-dom": ["@types/[email protected]", "", { "peerDependencies": { "@types/react": "^19.3.0" } }, "sha512-ZI7bU42mZXXKHn/qNLEw2IrbiINU7X5+vfgdixBHkCNpYWXjKgfQ/P+uyGb5CjOLB9UcnTeg3rylQtV2hym44Q=="],
"bun-types": ["[email protected]", "", { "dependencies": { "@types/node": "*", "undici-types": "*" } }, "sha512-yjrJh5oGX7mMPKGd19YXyIjmEuj4G4zNC30bs7PM9Az7NQ3ndF3j6hbeRdvJTRQEhJ/FYQwW0a2moweEi2hMxQ=="],
"csstype": ["[email protected]", "", {}, "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ=="],
"react": ["[email protected]", "", {}, "sha512-QNhWdt7nrgVWWQG58QuGsAR3jv3Hbe4mb4vz7w2csnHavciZJgda1CPNaldF6eVxv90ud3jUXpKlHL69gO38yw=="],
"react-dom": ["[email protected]", "", { "dependencies": { "scheduler": "^0.28.0" }, "peerDependencies": { "react": "^19.3.1" } }, "sha512-Y0bARz53lhEC1NMCASs0/j+faB/zqt3R8hpvg1e8+61ZVJ4UL0UdC4cBbXfZMcIuhrfgeILTLe+ZeBCavQPtKQ=="],
"react-router": ["[email protected]", "", { "dependencies": { "@remix-run/router": "1.23.4" }, "peerDependencies": { "react": ">=16.8" } }, "sha512-5HfK7k5im7LTOB0EqCQmfvy4C13G92Ssj1VTmouTK3AJvyjKTnFuCV0vcMAD/JS+JC4DvDIBRrlAeJIFjh5VWg=="],
"react-router-dom": ["[email protected]", "", { "dependencies": { "@remix-run/router": "1.23.4", "react-router": "6.30.6" }, "peerDependencies": { "react": ">=16.8", "react-dom": ">=16.8" } }, "sha512-0RHKZz7wwffvkU+2MFVT2NnjK44ssLEV+m0CAJaS2Ksmorrwj7WxH00jO0SOCW26/tINUnJHToXblDs33I38YQ=="],
"scheduler": ["[email protected]", "", {}, "sha512-juorfCmIkIw8tT+p5BXSm6PJjQF/ycEYmKyzURCIt/RaZIhL+PulbQ9Yu2z1HdOJDdqDTlxA1+xKBmHXJsczAw=="],
"typescript": ["[email protected]", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
"undici-types": ["[email protected]", "", {}, "sha512-EXE4ydL3S76dFb27UFjNVZHTyv/TLdATj/KUe29ptdcg6qXL48J2tZ3126E5kICj5jn781OR+XlVH1N6Mz8jbA=="],
+9
View File
@@ -10,7 +10,16 @@
},
"devDependencies": {
"@types/react": "^19",
"@types/react-dom": "^19.3.0",
"bun-types": "^1.3.14",
"typescript": "^5"
},
"dependencies": {
"@fontsource/ibm-plex-mono": "^5.3.0",
"@fontsource/ibm-plex-sans": "^5.3.0",
"@fontsource/literata": "^5.3.0",
"react": "^19.3.1",
"react-dom": "^19.3.1",
"react-router-dom": "6"
}
}
+13
View File
@@ -0,0 +1,13 @@
import type { ReactNode } from "react";
export function AppShell({ header, sidebar, children }: { header?: ReactNode; sidebar?: ReactNode; children: ReactNode }) {
return (
<>
{header ? <header className="stc-top">{header}</header> : null}
<div className="stc-shell">
{sidebar ? <aside className="stc-side">{sidebar}</aside> : null}
<main className="stc-main">{children}</main>
</div>
</>
);
}
+7
View File
@@ -0,0 +1,7 @@
@import "@fontsource/ibm-plex-sans/400.css";
@import "@fontsource/ibm-plex-sans/500.css";
@import "@fontsource/ibm-plex-sans/600.css";
@import "@fontsource/ibm-plex-mono/400.css";
@import "@fontsource/literata/400.css";
@import "@fontsource/literata/600.css";
@import "@fontsource/literata/400-italic.css";
+2
View File
@@ -0,0 +1,2 @@
export { AppShell } from "./AppShell";
export { Pill, SegmentedToggle, ProgressBar, FloatingActionBar, CourseCover, monogram } from "./primitives";
+46
View File
@@ -0,0 +1,46 @@
import type { ButtonHTMLAttributes, CSSProperties, ReactNode } from "react";
export function Pill({ variant = "default", className, ...rest }: { variant?: "default" | "primary" | "ghost" } & ButtonHTMLAttributes<HTMLButtonElement>) {
const cls = ["stc-pill", variant !== "default" && `stc-pill--${variant}`, className].filter(Boolean).join(" ");
return <button type="button" {...rest} className={cls} />;
}
export function SegmentedToggle({ options, value, onChange, label }: {
options: { value: string; label: string }[]; value: string; onChange: (v: string) => void; label: string;
}) {
return (
<div className="stc-seg" role="group" aria-label={label}>
{options.map((o) => (
<button key={o.value} type="button" aria-pressed={o.value === value} onClick={() => onChange(o.value)}>{o.label}</button>
))}
</div>
);
}
export function ProgressBar({ value, dim, label }: { value: number; dim?: boolean; label: string }) {
const pct = Math.round(Math.min(1, Math.max(0, value)) * 100);
return (
<span className={dim ? "stc-bar stc-bar--dim" : "stc-bar"} role="progressbar" aria-label={label} aria-valuemin={0} aria-valuemax={100} aria-valuenow={pct}>
<i style={{ width: `${pct}%` }} />
</span>
);
}
export function FloatingActionBar({ children }: { children: ReactNode }) {
return <div className="stc-dock" role="toolbar">{children}</div>;
}
export function monogram(title: string): string {
const words = title.trim().split(/\s+/).filter(Boolean);
const letters = words.length >= 2 ? [words[0]![0], words[1]![0]] : Array.from(words[0] ?? "?").slice(0, 2);
return letters.join("").toUpperCase();
}
export function CourseCover({ title, image, accent }: { title: string; image?: string; accent?: string }) {
const style = accent ? ({ "--cfg": accent } as CSSProperties) : undefined;
return (
<div className="stc-cover" style={style} role="img" aria-label={title}>
{image ? <img src={image} alt="" /> : <span aria-hidden="true">{monogram(title)}</span>}
</div>
);
}
+59
View File
@@ -0,0 +1,59 @@
:root {
--ground: #12141a; --side: #181b22; --raised: #232733; --line: #262a33; --line2: #343947;
--text: #d9dce3; --read: #d9d4c8; --head: #f2efe8; --muted: #a4abb8; --faint: #8c93a0;
--accent: #f1b44c; --accent-dim: #8c7440; --on-accent: #12141a;
--ok: #86c79f; --bad: #ee8f8f;
--sans: "IBM Plex Sans", ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
--serif: "Literata", Georgia, "Times New Roman", serif;
--mono: "IBM Plex Mono", ui-monospace, "SFMono-Regular", Menlo, Consolas, monospace;
--top: 52px; --sidew: 296px; --fast: 140ms;
color-scheme: dark;
}
*, *::before, *::after { box-sizing: border-box; }
body { margin: 0; background: var(--ground); color: var(--text); font: 400 14px/1.5 var(--sans); -webkit-font-smoothing: antialiased; }
a { color: inherit; }
button, input, textarea { font: inherit; color: inherit; }
button { cursor: pointer; }
code, pre { font-family: var(--mono); }
:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
::selection { background: color-mix(in srgb, var(--accent) 35%, transparent); }
.sr { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; }
.reading { font-family: var(--serif); font-size: 19px; line-height: 1.75; color: var(--read); max-width: 660px; }
.work { font-family: var(--sans); font-size: 15.5px; line-height: 1.6; color: var(--text); max-width: 760px; }
/* shell */
.stc-top { position: sticky; top: 0; z-index: 30; height: var(--top); display: flex; align-items: center; gap: 14px; padding: 0 16px; background: var(--ground); border-bottom: 1px solid var(--line); }
.stc-shell { display: flex; align-items: flex-start; }
.stc-side { position: sticky; top: var(--top); flex: none; width: var(--sidew); height: calc(100vh - var(--top)); overflow-y: auto; background: var(--side); border-right: 1px solid var(--line); }
.stc-main { flex: 1; min-width: 0; padding: 44px 40px 0; }
/* pill */
.stc-pill { display: inline-flex; align-items: center; gap: 8px; height: 34px; padding: 0 15px; border: 1px solid var(--line2); border-radius: 18px; background: none; font-size: 13px; font-weight: 500; text-decoration: none; white-space: nowrap; transition: background var(--fast), color var(--fast), border-color var(--fast); }
.stc-pill:hover { background: var(--raised); }
.stc-pill--primary { background: var(--accent); border-color: var(--accent); color: var(--on-accent); }
.stc-pill--primary:hover { background: color-mix(in srgb, var(--accent) 86%, #fff); }
.stc-pill--ghost { border-color: transparent; color: var(--muted); }
.stc-pill--ghost:hover { color: var(--text); }
.stc-pill:disabled { opacity: .45; cursor: default; }
/* segmented toggle */
.stc-seg { display: inline-flex; padding: 2px; border: 1px solid var(--line2); border-radius: 20px; flex: none; }
.stc-seg button { border: 0; background: none; height: 28px; padding: 0 13px; border-radius: 16px; font-size: 12.5px; font-weight: 500; color: var(--faint); transition: background var(--fast), color var(--fast); }
.stc-seg button:hover { color: var(--text); }
.stc-seg button[aria-pressed="true"] { background: var(--raised); color: var(--head); }
/* progress */
.stc-bar { display: block; flex: 1; height: 4px; border-radius: 2px; background: var(--line); overflow: hidden; }
.stc-bar > i { display: block; height: 100%; background: var(--accent); border-radius: 2px; }
.stc-bar--dim > i { background: var(--accent-dim); }
/* floating action bar */
.stc-dock { position: sticky; bottom: 18px; z-index: 10; display: flex; width: max-content; max-width: 100%; margin: 56px auto 18px; gap: 4px; padding: 5px; background: var(--raised); border: 1px solid var(--line2); border-radius: 24px; box-shadow: 0 0 0 10px var(--ground); }
.stc-dock .stc-pill { height: 36px; border-color: transparent; }
.stc-dock .stc-pill:hover { background: var(--line2); }
.stc-dock .stc-pill--primary:hover { background: color-mix(in srgb, var(--accent) 86%, #fff); }
/* cover */
.stc-cover { flex: none; position: relative; width: var(--cw, 44px); aspect-ratio: 3 / 4; border-radius: 6px; background: var(--cbg, var(--raised)); color: var(--cfg, var(--accent)); border: 1px solid color-mix(in srgb, var(--cfg, var(--accent)) 18%, transparent); overflow: hidden; font: 600 calc(var(--cw, 44px) * .34) / 1 var(--sans); letter-spacing: -.03em; display: flex; align-items: flex-end; padding: calc(var(--cw, 44px) * .12); }
.stc-cover img { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; }
+19
View File
@@ -0,0 +1,19 @@
import { expect, test } from "bun:test";
import { renderToString } from "react-dom/server";
import { CourseCover, ProgressBar, SegmentedToggle } from "../src";
test("ProgressBar exposes aria-valuenow as a percentage", () => {
const html = renderToString(<ProgressBar value={0.4} label="Course progress" />);
expect(html).toContain('role="progressbar"');
expect(html).toContain('aria-valuenow="40"');
});
test("CourseCover without an image shows a two-letter monogram", () => {
expect(renderToString(<CourseCover title="Pure Snake" />)).toContain(">PS<");
expect(renderToString(<CourseCover title="Docker" />)).toContain(">DO<");
});
test("SegmentedToggle marks the active option", () => {
const html = renderToString(<SegmentedToggle label="Look" value="b" onChange={() => {}} options={[{ value: "a", label: "A" }, { value: "b", label: "B" }]} />);
expect(html).toMatch(/aria-pressed="true"[^>]*>B</);
});