@twango/twiki 0.0.0-stage → 0.1.1

package/site/src/lib/components/search/pagefind-query.ts

@@ -0,0 +1,22 @@
+export interface ParsedSearchQuery {
+	/** `null` asks Pagefind for filter-only results. */
+	term: string | null;
+	/** Quartz-compatible leading `#tag` filter. */
+	tag?: string;
+}
+
+/**
+ * Quartz treated a leading `#tag` as a tag search. Preserve that shorthand
+ * while still allowing free text after the tag (`#cs544 spark`).
+ */
+export function parseSearchQuery(value: string): ParsedSearchQuery {
+	const query = value.trim();
+	const tagged = /^#([^\s]+)(?:\s+([\s\S]*))?$/.exec(query);
+	if (!tagged) return { term: query };
+
+	const remainder = tagged[2]?.trim() ?? '';
+	return {
+		term: remainder === '' ? null : remainder,
+		tag: tagged[1]
+	};
+}

package/site/src/lib/components/search/pagefind-url.ts

@@ -0,0 +1,12 @@
+/** Convert Pagefind HTML paths to extensionless routes, preserving anchors. */
+export function cleanResultUrl(raw: string): string {
+	const hashIdx = raw.indexOf('#');
+	const anchor = hashIdx === -1 ? '' : raw.slice(hashIdx);
+	let path = hashIdx === -1 ? raw : raw.slice(0, hashIdx);
+	path = path.replace(/\.html$/, '');
+	// Pagefind already maps `index.html` -> `/`, but normalize defensively.
+	if (path.endsWith('/index')) path = path.slice(0, -'index'.length);
+	if (path.length > 1 && path.endsWith('/')) path = path.slice(0, -1);
+	if (path === '') path = '/';
+	return path + anchor;
+}

package/site/src/lib/components/search/search-state.svelte.ts

@@ -0,0 +1,22 @@
+import { ensureIndex } from './pagefind-client.svelte';
+
+/**
+ * Shared palette open state (ported from cca): triggers (header button,
+ * `/` and Cmd/Ctrl+K bindings) live in different layout regions from the
+ * palette itself.
+ */
+export const searchState = $state({ open: false });
+
+export function openSearch(): void {
+	searchState.open = true;
+	void ensureIndex();
+}
+
+export function closeSearch(): void {
+	searchState.open = false;
+}
+
+export function toggleSearch(): void {
+	if (searchState.open) closeSearch();
+	else openSearch();
+}

package/site/src/lib/components/ui/IconButton.svelte

@@ -0,0 +1,30 @@
+<script lang="ts">
+	import type { HTMLButtonAttributes } from 'svelte/elements';
+	import { onMount, type Snippet } from 'svelte';
+	import { cn } from '$lib/utils';
+
+	type Props = HTMLButtonAttributes & {
+		'aria-label': string;
+		active?: boolean;
+		children: Snippet;
+	};
+
+	let { class: className, active = false, children, type = 'button', ...rest }: Props = $props();
+	let ready = $state(false);
+	onMount(() => {
+		ready = true;
+	});
+</script>
+
+<button
+	{type}
+	class={cn(
+		'inline-flex size-9 shrink-0 cursor-pointer items-center justify-center rounded-lg text-muted transition-colors hover:bg-surface hover:text-text focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none disabled:pointer-events-none disabled:opacity-50',
+		active && 'bg-accent-soft text-accent hover:bg-accent-soft hover:text-accent',
+		className
+	)}
+	{...rest}
+	disabled={!ready || rest.disabled}
+>
+	{@render children()}
+</button>

package/site/src/lib/components/ui/ThemeToggle.svelte

@@ -0,0 +1,22 @@
+<script lang="ts">
+	import Moon from '@lucide/svelte/icons/moon';
+	import Sun from '@lucide/svelte/icons/sun';
+	import { mode, toggleMode } from 'mode-watcher';
+	import IconButton from './IconButton.svelte';
+	import type { ClassValue } from 'svelte/elements';
+
+	let { class: className }: { class?: ClassValue } = $props();
+</script>
+
+<IconButton
+	onclick={toggleMode}
+	aria-label="Toggle dark mode"
+	title="Toggle theme"
+	class={className}
+>
+	{#if mode.current === 'dark'}
+		<Sun class="size-4" />
+	{:else}
+		<Moon class="size-4" />
+	{/if}
+</IconButton>

package/site/src/lib/components/ui/index.ts

@@ -0,0 +1 @@
+export { default as ThemeToggle } from './ThemeToggle.svelte';

package/site/src/lib/config.ts

@@ -0,0 +1,9 @@
+import metadata from './site-config.json';
+import authentication from './auth-config.json';
+
+/** Consumer branding is copied into the staged engine before any build or dev process. */
+export const site = metadata;
+
+/** Only configured server authentication exposes account controls. Static exports have no session API. */
+export const authEnabled =
+	authentication.enabled === true && import.meta.env?.VITE_STATIC_EXPORT !== 'true';

package/site/src/lib/content-license.ts

@@ -0,0 +1,7 @@
+export interface ContentLicense {
+	name: string;
+	url: string;
+	attribution: string;
+	source: string;
+	changes?: string;
+}

package/site/src/lib/file-history.ts

@@ -0,0 +1,37 @@
+export interface FileCommit {
+	id: string;
+	author: string;
+	date: string;
+	subject: string;
+}
+
+export interface FileChange extends FileCommit {
+	path: string;
+	previousPath?: string;
+	diff?: string;
+	unavailable?: string;
+}
+
+export interface FileHistory {
+	revision: string;
+	commits: FileChange[];
+	blame?: string;
+	notice?: string;
+}
+
+export interface FileBlame {
+	commits: Record<string, FileCommit>;
+	ranges: [start: number, end: number, commit: string][];
+}
+
+export function blameAt(blame: FileBlame, line: number) {
+	let low = 0,
+		high = blame.ranges.length - 1;
+	while (low <= high) {
+		const middle = (low + high) >>> 1;
+		const range = blame.ranges[middle];
+		if (line < range[0]) high = middle - 1;
+		else if (line > range[1]) low = middle + 1;
+		else return { commit: blame.commits[range[2]], start: range[0] };
+	}
+}

package/site/src/lib/file-icons.ts

@@ -0,0 +1,27 @@
+export interface IconVariants {
+	light: string;
+	dark: string;
+}
+
+export interface FolderIconVariants extends IconVariants {
+	expanded: IconVariants;
+}
+
+export interface FileIconTheme {
+	file: IconVariants;
+	folder: FolderIconVariants;
+	files: Record<string, IconVariants>;
+	folders: Record<string, FolderIconVariants>;
+}
+
+export function selectFileIcon(
+	theme: FileIconTheme,
+	name: string,
+	folder = false,
+	expanded = false
+): IconVariants {
+	const key = name.toLowerCase();
+	if (!folder) return Object.hasOwn(theme.files, key) ? theme.files[key] : theme.file;
+	const icon = Object.hasOwn(theme.folders, key) ? theme.folders[key] : theme.folder;
+	return expanded ? icon.expanded : icon;
+}

package/site/src/lib/file-tabs.ts

@@ -0,0 +1,72 @@
+export interface FileTab {
+	course: string;
+	path: string;
+	pinned: boolean;
+	top: number;
+	left: number;
+}
+
+export function sameFile(a: Pick<FileTab, 'course' | 'path'>, b: Pick<FileTab, 'course' | 'path'>) {
+	return a.course === b.course && a.path === b.path;
+}
+
+export function openFile(tabs: FileTab[], course: string, path: string, pinned = false): FileTab[] {
+	const existing = tabs.findIndex((tab) => sameFile(tab, { course, path }));
+	if (existing >= 0)
+		return tabs.map((tab, i) => (i === existing && pinned ? { ...tab, pinned: true } : tab));
+	const next = { course, path, pinned, top: 0, left: 0 };
+	const preview = tabs.findIndex((tab) => !tab.pinned);
+	return preview < 0 ? [...tabs, next] : tabs.map((tab, i) => (i === preview ? next : tab));
+}
+
+export function restoreTabs(value: string | null): FileTab[] {
+	try {
+		const parsed: unknown = JSON.parse(value ?? '[]');
+		if (!Array.isArray(parsed)) return [];
+		const tabs: FileTab[] = [];
+		for (const tab of parsed.slice(0, 100)) {
+			if (
+				!tab ||
+				typeof tab.course !== 'string' ||
+				typeof tab.path !== 'string' ||
+				!tab.course ||
+				!tab.path ||
+				tab.course.length > 200 ||
+				tab.path.length > 2000
+			)
+				continue;
+			if (tabs.some((existing) => sameFile(existing, tab))) continue;
+			tabs.push({
+				course: tab.course,
+				path: tab.path,
+				pinned: tab.pinned === true || tabs.some((item) => !item.pinned),
+				top: Number.isFinite(tab.top) ? Math.max(0, tab.top) : 0,
+				left: Number.isFinite(tab.left) ? Math.max(0, tab.left) : 0
+			});
+		}
+		return tabs;
+	} catch {
+		return [];
+	}
+}
+
+export function moveTab(tabs: FileTab[], tab: FileTab, destination: number): FileTab[] {
+	const index = tabs.findIndex((item) => sameFile(item, tab));
+	if (index < 0 || !Number.isInteger(destination)) return tabs;
+	if (index === destination && tabs[index].pinned) return tabs;
+	const reordered = [...tabs];
+	const [moved] = reordered.splice(index, 1);
+	reordered.splice(Math.max(0, Math.min(destination, reordered.length)), 0, {
+		...moved,
+		pinned: true
+	});
+	return reordered;
+}
+
+export function tabLabel(tab: FileTab, tabs: FileTab[]) {
+	const name = tab.path.split('/').at(-1)!;
+	const duplicate = tabs.some(
+		(other) => !sameFile(tab, other) && other.path.split('/').at(-1) === name
+	);
+	return duplicate ? `${name} · ${tab.course}/${tab.path.split('/').slice(0, -1).join('/')}` : name;
+}

package/site/src/lib/files.ts

@@ -0,0 +1,73 @@
+export interface CourseFile {
+	locked?: boolean;
+	license?: import('./content-license').ContentLicense;
+	path: string;
+	size: number;
+	kind: 'text' | 'image' | 'pdf' | 'binary';
+	download?: string;
+	history?: string;
+	rmdPreview?: string;
+	note?: string;
+}
+
+export interface RmdPreview {
+	title: string;
+	html: string;
+}
+
+export interface FileNode {
+	name: string;
+	path: string;
+	children?: FileNode[];
+	file?: CourseFile;
+}
+
+export function fileRoute(course: string, path = '') {
+	return `/${encodeURIComponent(course)}/files${path ? '/' + path.split('/').map(encodeURIComponent).join('/') : ''}`;
+}
+
+export function fileIndexUrl(course: string) {
+	return `/_files/index/${encodeURIComponent(course)}.json`;
+}
+
+export function fileTree(files: CourseFile[]): FileNode[] {
+	const root: FileNode[] = [];
+	for (const file of files) {
+		const segments = file.path.split('/');
+		let children = root;
+		for (let i = 0; i < segments.length; i++) {
+			const name = segments[i];
+			let node = children.find((entry) => entry.name === name);
+			if (!node) {
+				node = { name, path: segments.slice(0, i + 1).join('/') };
+				children.push(node);
+			}
+			if (i === segments.length - 1) node.file = file;
+			else children = node.children ??= [];
+		}
+	}
+	function sort(nodes: FileNode[]) {
+		nodes.sort(
+			(a, b) =>
+				Number(!!b.children) - Number(!!a.children) ||
+				a.name.localeCompare(b.name, undefined, { numeric: true })
+		);
+		for (const node of nodes) if (node.children) sort(node.children);
+	}
+	sort(root);
+	return root;
+}
+
+export function directoryEntries(tree: FileNode[], path: string): FileNode[] | undefined {
+	let entries: FileNode[] | undefined = tree;
+	for (const segment of path.split('/').filter(Boolean)) {
+		entries = entries?.find((node) => node.name === segment)?.children;
+	}
+	return entries;
+}
+
+export function fileSize(bytes: number) {
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1048576) return `${(bytes / 1024).toFixed(1)} KB`;
+	return `${(bytes / 1048576).toFixed(1)} MB`;
+}

package/site/src/lib/github-user.ts

@@ -0,0 +1,70 @@
+export const githubUsername = /^[a-z\d](?:[a-z\d-]{0,37}[a-z\d])?$/i;
+type Lookup = { user: { id: string; login: string } } | { status: number; error: string };
+
+export async function lookupGithubUser(
+	value: FormDataEntryValue | null,
+	fetcher = fetch
+): Promise<Lookup> {
+	const username = typeof value === 'string' ? value.trim().replace(/^@/, '') : '';
+	if (!githubUsername.test(username))
+		return { status: 400, error: 'Enter a valid GitHub username.' };
+	try {
+		const response = await fetcher(`https://api.github.com/users/${encodeURIComponent(username)}`, {
+			headers: {
+				Accept: 'application/vnd.github+json',
+				'X-GitHub-Api-Version': '2026-03-10'
+			},
+			credentials: 'omit',
+			redirect: 'error',
+			signal: AbortSignal.timeout(5000)
+		});
+		if (response.status === 404)
+			return { status: 404, error: 'That GitHub account was not found.' };
+		if (!response.ok) {
+			console.warn('GitHub user lookup rejected', {
+				status: response.status,
+				requestId: response.headers.get('x-github-request-id'),
+				rateLimitRemaining: response.headers.get('x-ratelimit-remaining'),
+				rateLimitReset: response.headers.get('x-ratelimit-reset'),
+				retryAfter: response.headers.get('retry-after')
+			});
+			const rateLimited =
+				response.status === 429 ||
+				(response.status === 403 &&
+					(response.headers.get('x-ratelimit-remaining') === '0' ||
+						response.headers.has('retry-after')));
+			return {
+				status: 503,
+				error: rateLimited
+					? 'GitHub has temporarily rate-limited account lookups. Please try again later.'
+					: `GitHub lookup failed (HTTP ${response.status}). Please try again later.`
+			};
+		}
+		const profile = (await response.json()) as { id?: number; login?: string; type?: string };
+		if (
+			!Number.isSafeInteger(profile.id) ||
+			profile.id! <= 0 ||
+			typeof profile.login !== 'string' ||
+			!githubUsername.test(profile.login) ||
+			profile.type !== 'User'
+		) {
+			return {
+				status: 400,
+				error: 'Choose a personal GitHub account, not an organization or bot.'
+			};
+		}
+		return { user: { id: String(profile.id), login: profile.login } };
+	} catch (cause) {
+		const kind = cause instanceof Error ? cause.name : 'UnknownError';
+		console.warn('GitHub user lookup failed', { kind });
+		return {
+			status: 503,
+			error:
+				kind === 'TimeoutError' || kind === 'AbortError'
+					? 'GitHub lookup timed out. Please try again.'
+					: kind === 'SyntaxError'
+						? 'GitHub returned an unreadable response. Please try again later.'
+						: 'Could not connect to GitHub for account lookup. Please try again later.'
+		};
+	}
+}

package/site/src/lib/metadata.ts

@@ -0,0 +1,166 @@
+import { site } from './config';
+import { socialImageUrl } from './social-image';
+import type { ManifestPage } from './types';
+
+export interface ContentAuthor {
+	name: string;
+	url?: string;
+	type: 'Person' | 'Organization';
+}
+
+export function configuredCurator(): ContentAuthor | undefined {
+	return site.author.name.trim()
+		? {
+				name: site.author.name,
+				...(site.author.url ? { url: site.author.url } : {}),
+				type: 'Person'
+			}
+		: undefined;
+}
+
+/** UI fallback follows the consumer-provided author, when configured. */
+export const curator = configuredCurator();
+
+export function contentAuthor(value: unknown): ContentAuthor | undefined {
+	if (typeof value === 'string')
+		return value.trim() ? { name: value.trim(), type: 'Person' } : undefined;
+	if (!value || typeof value !== 'object' || Array.isArray(value)) return;
+	const author = value as Record<string, unknown>;
+	if (typeof author.name !== 'string' || !author.name.trim()) return;
+	let url: string | undefined;
+	if (typeof author.url === 'string') {
+		try {
+			const parsed = new URL(author.url);
+			if (['https:', 'http:'].includes(parsed.protocol)) url = parsed.href;
+		} catch {}
+	}
+	return {
+		name: author.name.trim(),
+		type: author.type === 'Organization' ? 'Organization' : 'Person',
+		...(url ? { url } : {})
+	};
+}
+
+export function pageAuthor(
+	page: Pick<ManifestPage, 'slug' | 'license'> & { author?: ContentAuthor }
+) {
+	return (
+		page.author ??
+		(/^[^/]+\/README$/.test(page.slug) && !page.license ? configuredCurator() : undefined)
+	);
+}
+
+export function breadcrumbs(route: string, title: string) {
+	const segments = route
+		.replace(/^\/|\/$/g, '')
+		.split('/')
+		.filter(Boolean);
+	if (!segments.length) return [];
+	return [
+		{ label: 'Home', href: '/' },
+		...segments.map((segment, index) => ({
+			label: index === segments.length - 1 ? title : segment,
+			href: '/' + segments.slice(0, index + 1).join('/')
+		}))
+	];
+}
+
+export function canonicalUrl(route: string) {
+	return new URL('/' + route.replace(/^\/+/, ''), site.url).href;
+}
+
+export function serializeSchema(schema: Record<string, unknown>) {
+	return JSON.stringify(schema)
+		.replaceAll('<', '\\u003c')
+		.replaceAll('>', '\\u003e')
+		.replaceAll('&', '\\u0026');
+}
+
+function personSchema(author: ContentAuthor) {
+	return { '@type': author.type, name: author.name, ...(author.url ? { url: author.url } : {}) };
+}
+
+export function collectionSchema(route: string, title: string, description: string) {
+	const url = canonicalUrl(route);
+	const website = {
+		'@context': 'https://schema.org',
+		'@type': 'WebSite',
+		'@id': `${site.url}/#website`,
+		url: `${site.url}/`,
+		name: site.name,
+		description: site.description,
+		inLanguage: site.language,
+		...(configuredCurator() ? { publisher: personSchema(configuredCurator()!) } : {})
+	};
+	const collection = {
+		'@context': 'https://schema.org',
+		'@type': 'CollectionPage',
+		'@id': `${url}#webpage`,
+		url,
+		name: title,
+		image: socialImageUrl(),
+		description,
+		inLanguage: site.language,
+		isPartOf: { '@id': website['@id'] }
+	};
+	return [website, collection, ...breadcrumbSchema(route, title)];
+}
+
+function breadcrumbSchema(route: string, title: string) {
+	const trail = breadcrumbs(route, title);
+	return trail.length
+		? [
+				{
+					'@context': 'https://schema.org',
+					'@type': 'BreadcrumbList',
+					itemListElement: trail.map((crumb, index) => ({
+						'@type': 'ListItem',
+						position: index + 1,
+						name: crumb.label,
+						item: canonicalUrl(crumb.href)
+					}))
+				}
+			]
+		: [];
+}
+
+export function noteSchema(route: string, page: Omit<ManifestPage, 'backlinks'>) {
+	if (page.locked || !page.publication.public) return [];
+	const url = canonicalUrl(route);
+	const author = pageAuthor(page);
+	const collection =
+		page.slug === 'index' || page.slug.endsWith('/index') || /^[^/]+\/README$/.test(page.slug);
+	const schema = {
+		'@context': 'https://schema.org',
+		'@type': collection ? 'CollectionPage' : 'Article',
+		'@id': `${url}#${collection ? 'webpage' : 'article'}`,
+		url,
+		name: page.title,
+		image: [socialImageUrl(page.slug)],
+		headline: page.title,
+		description: page.description,
+		mainEntityOfPage: url,
+		inLanguage: site.language,
+		isPartOf: { '@id': `${site.url}/#website` },
+		...(author ? { author: personSchema(author) } : {}),
+		...(configuredCurator() ? { editor: personSchema(configuredCurator()!) } : {}),
+		...(page.dates.created ? { dateCreated: page.dates.created } : {}),
+		...(page.dates.modified ? { dateModified: page.dates.modified } : {}),
+		...(page.dates.published ? { datePublished: page.dates.published } : {}),
+		...(page.tags.length ? { keywords: page.tags } : {}),
+		...(!collection ? { wordCount: page.wordCount } : {}),
+		isAccessibleForFree: true,
+		...(page.license
+			? {
+					license: page.license.url,
+					creditText: page.license.attribution,
+					isBasedOn: page.license.source
+				}
+			: {})
+	};
+	return [
+		collectionSchema('', site.name, site.description)[0],
+		schema,
+		...breadcrumbSchema(route, page.title)
+	];
+}

package/site/src/lib/notebook-nav.ts

@@ -0,0 +1,63 @@
+import { fileRoute, type CourseFile } from './files';
+import type { NavNode } from './types';
+
+/** Add executable worksheets to Notes without treating datasets as notes. */
+export function addNotebookNavigation(nav: NavNode[], course: string, files: CourseFile[]) {
+	const notebooks = files.filter((file) => /\.rmd$/i.test(file.path));
+	if (!notebooks.length) return;
+	let root = nav.find((node) => node.segment === course);
+	if (!root) {
+		root = { segment: course, title: course, route: fileRoute(course), children: [] };
+		nav.push(root);
+	}
+	for (const file of notebooks) {
+		const parts = file.path.split('/');
+		let children = root.children;
+		for (let i = 0; i < parts.length - 1; i++) {
+			const segment = parts[i];
+			let folder = children.find((node) => node.segment === segment);
+			if (!folder) {
+				folder = {
+					segment,
+					title: segment.charAt(0).toUpperCase() + segment.slice(1),
+					route: fileRoute(course, parts.slice(0, i + 1).join('/')),
+					notebook: true,
+					children: []
+				};
+				children.push(folder);
+			}
+			children = folder.children;
+		}
+		const segment = parts.at(-1)!;
+		if (!children.some((node) => node.segment === segment))
+			children.push({
+				segment,
+				title:
+					segment
+						.replace(/\.rmd$/i, '')
+						.replace(/[-_]/g, ' ')
+						.replace(/^./, (c) => c.toUpperCase()) + ' (R worksheet)',
+				route: fileRoute(course, file.path),
+				notebook: true,
+				locked: file.locked,
+				children: []
+			});
+	}
+	function sort(nodes: NavNode[]) {
+		nodes.sort(
+			(a, b) =>
+				Number(!!b.children.length) - Number(!!a.children.length) ||
+				a.title.localeCompare(b.title, undefined, { numeric: true })
+		);
+		for (const node of nodes) sort(node.children);
+	}
+	sort(root.children);
+}
+
+export function isNotebookRoute(nodes: NavNode[], path: string): boolean {
+	return nodes.some(
+		(node) =>
+			(node.notebook && decodeURI(node.route ?? '') === path.replace(/\/$/, '')) ||
+			isNotebookRoute(node.children, path)
+	);
+}

package/site/src/lib/publication.ts

@@ -0,0 +1 @@
+export const publicEdition = import.meta.env.VITE_PUBLIC_EDITION === 'true';