@twango/twiki 0.0.0-stage → 0.1.1

package/site/src/lib/styles/foundation.css

@@ -0,0 +1,138 @@
+/* ---------------------------------------------------------------------------
+   Fonts — same set as twango.dev / cca (Overused Grotesk, JetBrains Mono, Virgil)
+--------------------------------------------------------------------------- */
+@font-face {
+	font-family: 'Overused Grotesk';
+	src: url('/fonts/OverusedGrotesk-VF.woff2') format('woff2');
+	font-weight: 300 900;
+	font-style: normal;
+	font-display: swap;
+}
+
+@font-face {
+	font-family: 'Overused Grotesk';
+	src: url('/fonts/OverusedGroteskItalic-VF.woff2') format('woff2');
+	font-weight: 400;
+	font-style: italic;
+	font-display: swap;
+}
+
+@font-face {
+	font-family: 'JetBrains Mono';
+	src: url('/fonts/JetBrainsMono-VF.woff2') format('woff2');
+	font-weight: 100 800;
+	font-style: normal;
+	font-display: swap;
+}
+
+@font-face {
+	font-family: 'JetBrains Mono';
+	src: url('/fonts/JetBrainsMono-Italic-VF.woff2') format('woff2');
+	font-weight: 100 800;
+	font-style: italic;
+	font-display: swap;
+}
+
+@font-face {
+	font-family: 'Virgil';
+	src: url('/fonts/Virgil.woff2') format('woff2');
+	font-weight: 400;
+	font-style: normal;
+	font-display: swap;
+}
+
+/* ---------------------------------------------------------------------------
+   Design tokens — cca's warm-paper palette, wisconsin's red accent
+--------------------------------------------------------------------------- */
+@theme {
+	--font-hand: 'Virgil', cursive;
+	--font-sans: 'Overused Grotesk', system-ui, sans-serif;
+	--font-mono: 'JetBrains Mono', ui-monospace, monospace;
+
+	--color-bg: #f8f6f1;
+	--color-surface: #efede7;
+	--color-text: #1a1916;
+	--color-muted: #8a8578;
+	--color-subtle: #e2dfd8;
+	--color-accent: #d35545;
+	--color-accent-soft: #f7e4e1;
+
+	--color-border: var(--color-subtle);
+}
+
+@theme static {
+	--breakpoint-rail: 1440px;
+}
+
+:root {
+	--graph-preview-height: 250px;
+}
+
+:root.dark {
+	--color-bg: #1a1916;
+	--color-surface: #23221e;
+	--color-text: #e8e5df;
+	--color-muted: #7a7568;
+	--color-subtle: #2e2d28;
+	--color-accent: #e68578;
+	--color-accent-soft: #3f1f1b;
+}
+
+html,
+body {
+	background-color: var(--color-bg);
+	color: var(--color-text);
+	font-family: var(--font-sans);
+	-webkit-font-smoothing: antialiased;
+	-moz-osx-font-smoothing: grayscale;
+}
+
+/* ---------------------------------------------------------------------------
+   Scrollbars — thin, theme-aware, unobtrusive (site-wide)
+--------------------------------------------------------------------------- */
+* {
+	scrollbar-width: thin;
+	scrollbar-color: var(--color-subtle) transparent;
+}
+*::-webkit-scrollbar {
+	width: 0.625rem;
+	height: 0.625rem;
+}
+*::-webkit-scrollbar-track {
+	background: transparent;
+}
+*::-webkit-scrollbar-thumb {
+	border: 3px solid transparent;
+	border-radius: 9999px;
+	background-color: var(--color-subtle);
+	background-clip: content-box;
+}
+*::-webkit-scrollbar-thumb:hover {
+	background-color: var(--color-muted);
+}
+
+code,
+kbd,
+samp,
+pre {
+	font-family: var(--font-mono);
+}
+
+/* ---------------------------------------------------------------------------
+   View transitions: subtle, quick crossfade between pages (onNavigate +
+   document.startViewTransition in +layout.svelte). Reduced motion is already
+   guarded in JS; the media query here is belt-and-braces.
+--------------------------------------------------------------------------- */
+@media (prefers-reduced-motion: no-preference) {
+	::view-transition-old(root),
+	::view-transition-new(root) {
+		animation-duration: 120ms;
+		animation-timing-function: ease;
+	}
+}
+@media (prefers-reduced-motion: reduce) {
+	::view-transition-old(root),
+	::view-transition-new(root) {
+		animation: none;
+	}
+}

package/site/src/lib/styles/print.css

@@ -0,0 +1,115 @@
+/* Shared by the note button and the browser's native Print command. */
+@page {
+	margin: 16mm;
+}
+
+@media print {
+	:root,
+	:root.dark {
+		color-scheme: light;
+		--color-bg: #fff;
+		--color-surface: #f5f5f5;
+		--color-text: #111;
+		--color-muted: #555;
+		--color-subtle: #ccc;
+		--color-accent: #111;
+	}
+
+	html,
+	body {
+		height: auto !important;
+		overflow: visible !important;
+		background: white;
+	}
+
+	.doc-shell {
+		display: block;
+		min-height: 0;
+	}
+
+	.doc-main {
+		padding: 0;
+	}
+
+	.doc-main > div {
+		max-width: none;
+		margin: 0;
+	}
+
+	.doc-sidebar-left,
+	.doc-sidebar-right,
+	.doc-mobile-header,
+	.doc-reader-controls,
+	.doc-nav-backdrop,
+	.doc-main nav,
+	[data-island='backlinks'],
+	.note-actions,
+	[data-bits-portal],
+	.popover,
+	.pswp,
+	.mermaid-modal,
+	.mermaid-toolbar,
+	.prose .copy-button,
+	.prose .heading-anchor,
+	.prose .fold-callout-icon {
+		display: none !important;
+	}
+
+	.prose {
+		font-size: 11pt;
+		orphans: 3;
+		widows: 3;
+	}
+
+	.prose :where(h1, h2, h3, h4, h5, h6) {
+		break-after: avoid;
+	}
+
+	.prose :where(img, svg, figure, tr) {
+		break-inside: avoid;
+	}
+
+	.prose :where(pre, pre code) {
+		white-space: pre-wrap;
+		overflow-wrap: anywhere;
+	}
+
+	.prose pre,
+	.prose pre span,
+	:root.dark .prose pre.shiki,
+	:root.dark .prose pre.shiki span {
+		color: #111 !important;
+		background: #f5f5f5 !important;
+		text-shadow: none;
+	}
+
+	.prose pre.shiki,
+	.prose .katex-display,
+	.prose .mermaid-diagram {
+		overflow: visible;
+	}
+
+	.prose .mermaid-inline-content {
+		min-width: 0;
+	}
+
+	.prose :where(img, .mermaid-inline-content > svg) {
+		max-width: 100%;
+		max-height: 240mm;
+		object-fit: contain;
+	}
+
+	/* Include folded callouts without changing the reader's screen state. */
+	.prose blockquote.callout > .callout-content {
+		display: block;
+	}
+
+	.prose .callout-content-inner {
+		overflow: visible;
+	}
+
+	.prose table {
+		width: 100%;
+		font-size: 9pt;
+	}
+}

package/site/src/lib/styles/shell.css

@@ -0,0 +1,182 @@
+/* Documentation shell: shared breakpoints own all rail and drawer geometry. */
+.doc-shell {
+	display: grid;
+	width: 100%;
+	grid-template-columns: 22rem minmax(0, 1fr) 22rem;
+	grid-template-areas: 'left main right';
+}
+.doc-shell-listing {
+	grid-template-columns: 22rem minmax(0, 1fr);
+	grid-template-areas: 'left main';
+}
+.doc-mobile-header {
+	display: none;
+	grid-area: mobile-header;
+}
+.doc-sidebar-left {
+	grid-area: left;
+	position: sticky;
+	top: 0;
+	height: 100dvh;
+}
+.doc-main {
+	grid-area: main;
+	padding: 2rem 2rem 3rem;
+}
+.doc-shell.doc-shell-files {
+	height: 100dvh;
+	min-height: 0;
+}
+.doc-main.doc-main-files {
+	min-height: 0;
+	padding: 0;
+}
+.doc-sidebar-right {
+	position: sticky;
+	top: 0;
+	grid-area: right;
+	height: 100dvh;
+	border-left: 1px solid var(--color-border);
+	background: var(--color-bg);
+	overflow-y: auto;
+	overscroll-behavior: contain;
+	padding: 0;
+}
+.doc-sidebar-right-inner {
+	display: flex;
+	min-height: 0;
+	flex-direction: column;
+}
+.doc-toc {
+	margin: 0;
+	border-top: 1px solid var(--color-border);
+	padding: 1rem 1rem 0.75rem;
+	max-height: calc(100dvh - var(--graph-preview-height));
+	overflow-anchor: none;
+	overflow-y: auto;
+	overscroll-behavior: contain;
+	scrollbar-width: thin;
+}
+.doc-toc .toc-header {
+	position: sticky;
+	top: 0;
+	z-index: 1;
+	background: var(--color-bg);
+}
+.doc-toc:where(:not(:has(nav))) {
+	display: none;
+}
+.doc-compact-graph,
+.doc-compact-outline {
+	display: none;
+}
+.doc-sidebar-content {
+	padding: 2rem 1rem 1rem;
+}
+.doc-shell-reader {
+	grid-template-columns: minmax(0, 1fr);
+	grid-template-areas: 'main';
+}
+.doc-shell-reader .doc-sidebar-left {
+	display: none;
+}
+.doc-nav-backdrop {
+	display: none;
+}
+
+@variant max-rail {
+	.doc-shell {
+		grid-template-columns: 18rem minmax(0, 1fr);
+		grid-template-areas: 'left right' 'left main';
+		grid-template-rows: auto 1fr;
+	}
+	.doc-shell-listing {
+		grid-template-areas: 'left main';
+	}
+	.doc-shell-reader {
+		grid-template-columns: minmax(0, 1fr);
+		grid-template-areas: 'main';
+	}
+	.doc-main {
+		padding-inline: 1.5rem;
+	}
+	.doc-sidebar-right {
+		position: static;
+		height: auto;
+		border-left: 0;
+		padding: 1.5rem 1.5rem 0;
+	}
+	.doc-sidebar-right-inner {
+		max-width: 48rem;
+		margin-inline: auto;
+		flex-direction: row;
+		align-items: start;
+		gap: 1rem;
+		flex-wrap: wrap;
+	}
+	.graph-panel {
+		display: none;
+	}
+	.doc-compact-graph,
+	.doc-compact-outline {
+		display: block;
+	}
+	.doc-compact-outline {
+		padding-block: 0.375rem;
+		flex: 1;
+		min-width: 10rem;
+	}
+	.doc-compact-outline nav {
+		margin-top: 0.75rem;
+	}
+	.doc-toc {
+		display: none;
+	}
+}
+@media (width < 1024px) {
+	.doc-shell,
+	.doc-shell-listing,
+	.doc-shell-reader {
+		grid-template-columns: minmax(0, 1fr);
+		grid-template-areas: 'mobile-header' 'right' 'main';
+		grid-template-rows: auto auto 1fr;
+	}
+	.doc-shell-listing,
+	.doc-shell-reader {
+		grid-template-areas: 'mobile-header' 'main';
+		grid-template-rows: auto 1fr;
+	}
+	.doc-mobile-header {
+		display: flex;
+	}
+	.doc-main {
+		padding: 1.5rem 1.25rem 2rem;
+	}
+	.doc-sidebar-left,
+	.doc-shell-reader .doc-sidebar-left {
+		display: block;
+		position: fixed;
+		top: 0;
+		left: 0;
+		z-index: 50;
+		width: 17rem;
+		max-width: 85vw;
+		transform: translateX(-100%);
+		transition: transform 200ms;
+	}
+	.doc-sidebar-left.doc-nav-open {
+		transform: translateX(0);
+	}
+	.doc-nav-backdrop {
+		display: block;
+	}
+	.doc-sidebar-content {
+		padding: 1.25rem 1rem;
+	}
+	.doc-reader-controls {
+		display: none;
+	}
+	.doc-sidebar-right {
+		padding-inline: 1.25rem;
+	}
+}

package/site/src/lib/text-exports.ts

@@ -0,0 +1,5 @@
+export function textExportUrl(slug: string, format: 'md' | 'txt' = 'md') {
+	// Folder index notes are displayed at the folder URL. Home uses /index.md.
+	const route = slug.replace(/\/index$/, '');
+	return `/${route.split('/').map(encodeURIComponent).join('/')}.${format}`;
+}

package/site/src/lib/types.ts

@@ -0,0 +1,140 @@
+/**
+ * Shared types for the doc shell and the prebuild content manifest
+ * (`site/build/generated`, emitted by `tooling/compiler.ts`).
+ */
+
+/** A node in the sidebar navigation tree (Explorer). */
+export interface NavNode {
+	/** Executable worksheet or its file-browser folder, shown in Notes. */
+	notebook?: boolean;
+	locked?: boolean;
+	title: string;
+	/** Route if this node is itself a page (folder landing pages, or leaf docs). No trailing slash. */
+	route?: string;
+	/** Child nodes (sections and pages), already naturally sorted (folders first). */
+	children: NavNode[];
+	/** Segment key used for sorting/keying within its parent. */
+	segment: string;
+}
+
+/** A flat table-of-contents entry for the right-hand rail. */
+export interface TocEntry {
+	id: string;
+	text: string;
+	/** Heading level (1–6); h1 = 1. */
+	level: number;
+}
+
+/** Raw TOC entry as emitted by the prebuild (`pages/<slug>.json`). */
+export interface RawTocEntry {
+	/** 0-based depth: 0 = h1. */
+	depth: number;
+	text: string;
+	/** github-slugger anchor id. */
+	slug: string;
+}
+
+/** Page dates from the prebuild (frontmatter → submodule git log → fs). */
+export interface PageDates {
+	created: string;
+	modified: string;
+	published: string;
+}
+
+/**
+ * A backlink reference. `slug` is in display form: folder index pages end in
+ * `/` (e.g. `sp26-cs537/exams/midterm-2/`), the homepage is `/`.
+ */
+export interface BacklinkRef {
+	slug: string;
+	title: string;
+}
+
+export interface PagePublication {
+	public: boolean;
+	reason?: string;
+}
+
+/** Per-page metadata as stored in `content-manifest.json` `pages`. */
+export interface ManifestPage {
+	heading?: string;
+	author?: import('./metadata').ContentAuthor;
+	locked?: boolean;
+	license?: import('./content-license').ContentLicense;
+	publication: PagePublication;
+	/** Canonical slug, e.g. `sp26-cs537/README` or `…/midterm-1/index` (no leading slash). */
+	slug: string;
+	title: string;
+	description: string;
+	tags: string[];
+	dates: PageDates;
+	/** Resolved outgoing link slugs (simple form). */
+	links: string[];
+	/** Backlink slugs (manifest stores display-form strings). */
+	backlinks: string[];
+	wordCount: number;
+	readingTime: number;
+	hasMermaid: boolean;
+	relativePath: string;
+}
+
+/** Full page document (`pages/<slug>.json`): manifest meta + rendered HTML. */
+export interface PageDoc extends Omit<ManifestPage, 'backlinks'> {
+	backlinks: BacklinkRef[];
+	toc: RawTocEntry[];
+	html: string;
+	markdown?: string;
+}
+
+/** A folder-tree node from `content-manifest.json` `tree`. */
+export interface TreeNode {
+	/** Last path segment (`midterm-1`); root is the site name. */
+	name: string;
+	/** Full folder slug (`sp26-cs537/exams/midterm-1`); root is ``. */
+	slug: string;
+	/** Index-page title when the folder has an `index.md`, else the name. */
+	title: string;
+	children: TreeNode[];
+	pages: { slug: string; title: string }[];
+}
+
+/** The global content manifest. */
+export interface ContentManifest {
+	fileCourses?: string[];
+	generatedAt: string;
+	counts: Record<string, number>;
+	pages: Record<string, ManifestPage>;
+	/** Every directory slug (with or without its own index page). */
+	folders: string[];
+	/** Tag → page slugs (case-sensitive tag keys). */
+	tags: Record<string, string[]>;
+	tree: TreeNode;
+	/** Asset paths (slugified, extensionful) copied to static output. */
+	assets: string[];
+	/** Standalone .html assets, stored extensionless (served via html_handling). */
+	htmlAssets: string[];
+	graph: {
+		nodes: { id: string; title: string; tags: string[] }[];
+		links: { source: string; target: string }[];
+	};
+}
+
+/** One entry in a generated folder-listing page. */
+export interface FolderEntry {
+	title: string;
+	route: string;
+	isFolder: boolean;
+	/** ISO modified date (pages only). */
+	modified?: string;
+}
+
+/** Data for a generated folder-listing page (folders without index.md). */
+export interface FolderListing {
+	/** Folder slug, e.g. `sp26-cs537/p1`. */
+	folder: string;
+	/** Display name (last segment). */
+	name: string;
+	entries: FolderEntry[];
+	/** Total pages anywhere under this folder. */
+	pageCount: number;
+}

package/site/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]) {
+	return twMerge(clsx(inputs));
+}

package/site/src/routes/+error.svelte

@@ -0,0 +1,16 @@
+<script lang="ts">
+	import { page } from '$app/state';
+	import SEO from '$lib/components/SEO.svelte';
+</script>
+
+<SEO title={String(page.status)} noindex />
+
+<article class="prose dark:prose-invert max-w-none">
+	<h1>{page.status}</h1>
+	{#if page.status === 404}
+		<p>Either this page is private or doesn't exist.</p>
+	{:else}
+		<p>{page.error?.message ?? 'Something went wrong.'}</p>
+	{/if}
+	<p><a href="/">Go back to the homepage</a></p>
+</article>

package/site/src/routes/+layout.server.ts

@@ -0,0 +1,10 @@
+import type { LayoutServerLoad } from './$types';
+import { requestContent } from '$lib/server/runtime-content';
+
+export const load: LayoutServerLoad = async ({ platform, url }) => {
+	// Track navigation so a stable application build still refreshes content data.
+	void url.pathname;
+	const content = requestContent(platform);
+	const [nav, fileIcons] = await Promise.all([content.nav(), content.icons()]);
+	return { nav, fileIcons, edition: content.context.edition };
+};

package/site/src/routes/+layout.svelte

@@ -0,0 +1,72 @@
+<script lang="ts">
+	import 'katex/dist/katex.min.css';
+	import './layout.css';
+	import { onMount, setContext, type Snippet } from 'svelte';
+	import { dev } from '$app/environment';
+	import { onNavigate, invalidateAll } from '$app/navigation';
+	import { ModeWatcher } from 'mode-watcher';
+	import { site } from '$lib/config';
+	import DocShell from '$lib/components/doc/DocShell.svelte';
+	import type { LayoutData } from './$types';
+
+	interface Props {
+		children: Snippet;
+		data: LayoutData;
+	}
+
+	const { children, data }: Props = $props();
+	const nav = $derived(data.nav ?? []);
+	setContext('wisconsin-file-icons', () => data.fileIcons);
+
+	onMount(() => {
+		if (dev) return;
+		void import('$lib/analytics')
+			.then(({ initializeAnalytics }) => initializeAnalytics())
+			.catch((error) => console.warn('Failed to initialize analytics', error));
+	});
+
+	if (import.meta.hot) {
+		const refreshContent = ({ recovered }: { recovered: boolean }) => {
+			if (recovered) document.querySelector('vite-error-overlay')?.remove();
+			void invalidateAll();
+		};
+		import.meta.hot.on('wisconsin:content', refreshContent);
+		import.meta.hot.dispose(() => import.meta.hot?.off('wisconsin:content', refreshContent));
+	}
+
+	// Subtle crossfade between pages via the View Transitions API
+	// (https://svelte.dev/blog/view-transitions). Progressive enhancement:
+	// no-ops in browsers without document.startViewTransition, and skipped
+	// for users who prefer reduced motion. Duration is tuned in foundation.css.
+	onNavigate((navigation) => {
+		if (
+			navigation.from?.route.id?.includes('/files/') &&
+			navigation.to?.route.id?.includes('/files/')
+		)
+			return;
+		if (!document.startViewTransition) return;
+		if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) return;
+
+		return new Promise((resolve) => {
+			document.startViewTransition(async () => {
+				resolve();
+				await navigation.complete;
+			});
+		});
+	});
+</script>
+
+<svelte:head>
+	<link rel="icon" href="/favicon.png" />
+	<link
+		rel="alternate"
+		type="application/rss+xml"
+		title={`${site.title} — recent notes`}
+		href="/index.xml"
+	/>
+</svelte:head>
+<ModeWatcher defaultMode="system" />
+
+<DocShell {nav}>
+	{@render children()}
+</DocShell>

package/site/src/routes/+layout.ts

@@ -0,0 +1,3 @@
+// Normal deployments render notes on the server; static export remains optional.
+export const prerender = import.meta.env.VITE_STATIC_EXPORT === 'true';
+export const trailingSlash = 'never';

package/site/src/routes/404/+page.svelte

@@ -0,0 +1,13 @@
+<script lang="ts">
+	// Prerendered as 404.html; Workers `assets.not_found_handling: "404-page"`
+	// serves it for any URL that matches neither an asset nor a route.
+	import SEO from '$lib/components/SEO.svelte';
+</script>
+
+<SEO title="404" noindex />
+
+<article class="prose dark:prose-invert max-w-none">
+	<h1>404</h1>
+	<p>Either this page is private or doesn't exist.</p>
+	<p><a href="/">Go back to the homepage</a></p>
+</article>