Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import { toWikiLinkSlug } from '@inkeep/open-knowledge-core/utils/slug';
import {
asTargetNamespace,
createTargetNamespace,
} from '@inkeep/open-knowledge-core/utils/target-namespace';
import { t } from '@lingui/core/macro';
import { createContext, type ReactNode, use, useEffect, useRef, useState } from 'react';
import {
buildPageIconsIndex,
buildPagesByBasenameIndex,
buildPagesBySlugIndex,
setPageListCache,
} from '@/editor/page-list-cache';
import { subscribeToDocumentsChanged } from '@/lib/documents-events';
import { fetchDocumentListShared } from '@/lib/documents-fetch';
import {
type DocumentTeardownObserver,
installDocumentTeardownObserver,
} from '@/lib/install-document-teardown-observer';
import { parseApiError } from '@/lib/parse-api-error';
import { pageListReady } from '@/lib/perf/startup-marks';
import { createRefreshScheduler } from '@/lib/refresh-scheduler';
import { deriveKnownFolderPaths } from './navigation-targets';
export const PUSH_REFRESH_COALESCE_MS = 300;
export interface PageMeta {
size: number;
modified: string;
docExt?: string;
icon?: string;
}
interface PageListContextValue {
pages: ReadonlySet<string>;
pagesBySlug: ReadonlyMap<string, string>;
pagesByBasename: ReadonlyMap<string, string>;
pageTitles: ReadonlyMap<string, string>;
pageMeta: ReadonlyMap<string, PageMeta>;
folderPaths: ReadonlySet<string>;
assetPaths: ReadonlySet<string>;
filePaths: ReadonlySet<string>;
loading: boolean;
error: string | null;
refetch: () => void;
addPage: (docName: string) => void;
}
const PageListContext = createContext<PageListContextValue | null>(null);
interface PageSummary {
docName: string;
title: string;
size: number;
modified: string;
docExt?: string;
icon?: string;
}
interface DocumentListEntry {
kind?: 'document' | 'asset' | 'folder' | 'file';
path?: string;
}
export function mergePageSets(
serverPages: ReadonlySet<string>,
optimisticPages: ReadonlySet<string>,
) {
if (optimisticPages.size === 0) return new Set(serverPages);
const merged = new Set(serverPages);
for (const docName of optimisticPages) merged.add(docName);
return merged;
}
export function pruneConfirmedOptimisticPages(
optimisticPages: ReadonlySet<string>,
serverPages: ReadonlySet<string>,
) {
if (optimisticPages.size === 0) return new Set<string>();
const pending = new Set<string>();
for (const docName of optimisticPages) {
if (!serverPages.has(docName)) pending.add(docName);
}
return pending;
}
function mergePageTitles(
serverTitles: ReadonlyMap<string, string>,
optimisticPages: ReadonlySet<string>,
) {
const merged = new Map(serverTitles);
for (const docName of optimisticPages) {
if (!merged.has(docName)) {
merged.set(docName, docName);
}
}
return merged;
}
async function loadPages(): Promise<PageSummary[]> {
const r = await fetch('/api/pages');
if (!r.ok) {
const body = (await r.json().catch(() => null)) as unknown;
throw new Error(parseApiError(body) ?? `/api/pages responded with ${r.status}`);
}
const data: { pages?: PageSummary[] } = await r.json();
if (Array.isArray(data.pages)) {
return data.pages;
}
return [];
}
async function loadDocumentListSummary(): Promise<{
assetPaths: string[];
folderPaths: string[];
filePaths: string[];
}> {
const { ok, status, body } = await fetchDocumentListShared();
if (!ok) {
throw new Error(parseApiError(body) ?? `/api/documents responded with ${status}`);
}
const data = (body ?? {}) as { documents?: DocumentListEntry[] };
if (!Array.isArray(data.documents)) {
throw new Error(parseApiError(body) ?? '/api/documents returned no usable documents field');
}
const assetPaths = data.documents
.filter((entry): entry is DocumentListEntry & { kind: 'asset'; path: string } => {
return entry.kind === 'asset' && typeof entry.path === 'string' && entry.path.length > 0;
})
.map((entry) => entry.path);
const folderPaths = data.documents
.filter((entry): entry is DocumentListEntry & { kind: 'folder'; path: string } => {
return entry.kind === 'folder' && typeof entry.path === 'string' && entry.path.length > 0;
})
.map((entry) => entry.path);
const filePaths = data.documents
.filter((entry): entry is DocumentListEntry & { kind: 'file'; path: string } => {
return entry.kind === 'file' && typeof entry.path === 'string' && entry.path.length > 0;
})
.map((entry) => entry.path);
return { assetPaths, folderPaths, filePaths };
}
function logLoadPagesError(err: unknown) {
console.error('[PageListContext] Failed to load pages:', err);
}
function logLoadAssetsError(err: unknown) {
console.warn('[PageListContext] Failed to load referenced assets:', err);
}
export function PageListProvider({ children }: { children: ReactNode }) {
const [serverPages, setServerPages] = useState(new Set<string>());
const [serverPageTitles, setServerPageTitles] = useState(new Map<string, string>());
const [serverPageMeta, setServerPageMeta] = useState(new Map<string, PageMeta>());
const [serverAssetPaths, setServerAssetPaths] = useState(new Set<string>());
const [serverFolderPaths, setServerFolderPaths] = useState(new Set<string>());
const [serverFilePaths, setServerFilePaths] = useState(new Set<string>());
const [optimisticPages, setOptimisticPages] = useState(new Set<string>());
const [loading, setLoading] = useState(true);
const [error, setError] = useState<string | null>(null);
const latestRequestIdRef = useRef(0);
const documentTeardownRef = useRef<DocumentTeardownObserver | null>(null);
function runRefresh(issuedWhileLive: boolean) {
const requestId = ++latestRequestIdRef.current;
const abandonedByTeardown = () =>
issuedWhileLive && documentTeardownRef.current?.isUnloading() === true;
return Promise.all([
loadPages().catch((err: unknown) => {
if (abandonedByTeardown()) return null;
throw err;
}),
loadDocumentListSummary().catch((err: unknown) => {
if (abandonedByTeardown()) return null;
logLoadAssetsError(err);
return { assetPaths: [], folderPaths: [], filePaths: [] };
}),
])
.then(([pageSummaries, documentList]) => {
if (requestId !== latestRequestIdRef.current) return;
if (pageSummaries === null) return;
const pageNames = new Set(pageSummaries.map((page) => page.docName));
setServerPages(pageNames);
setServerPageTitles(
new Map(pageSummaries.map((page) => [page.docName, page.title] as const)),
);
setServerPageMeta(
new Map(
pageSummaries.map(
(page) =>
[
page.docName,
{
size: page.size,
modified: page.modified,
docExt: page.docExt,
icon: page.icon,
},
] as const,
),
),
);
if (documentList !== null) {
setServerAssetPaths(new Set(documentList.assetPaths));
setServerFolderPaths(new Set(documentList.folderPaths));
setServerFilePaths(new Set(documentList.filePaths));
}
setOptimisticPages((prev) => pruneConfirmedOptimisticPages(prev, pageNames));
setError(null);
pageListReady();
})
.catch((err) => {
if (requestId !== latestRequestIdRef.current) return;
logLoadPagesError(err);
setError(err instanceof Error ? err.message : t`Failed to load pages`);
})
.finally(() => {
if (requestId !== latestRequestIdRef.current) return;
setLoading(false);
});
}
function refetch() {
return runRefresh(documentTeardownRef.current?.isUnloading() !== true);
}
function addPage(docName: string) {
setOptimisticPages((prev) => {
if (prev.has(docName)) return prev;
const next = new Set(prev);
next.add(docName);
return next;
});
setError(null);
}
// biome-ignore lint/correctness/useExhaustiveDependencies: run only on mount
useEffect(() => {
documentTeardownRef.current = installDocumentTeardownObserver();
let requestedWhileLive = true;
const scheduler = createRefreshScheduler(() => {
const issuedWhileLive = requestedWhileLive;
requestedWhileLive = true;
return runRefresh(issuedWhileLive);
});
const requestRefresh = () => {
if (documentTeardownRef.current?.isUnloading() === true) requestedWhileLive = false;
scheduler.request();
};
requestRefresh();
let pushFlushTimer: ReturnType<typeof setTimeout> | null = null;
const handleResume = () => {
if (document.visibilityState === 'visible') {
requestRefresh();
}
};
window.addEventListener('focus', handleResume);
window.addEventListener('visibilitychange', handleResume);
const unsubscribe = subscribeToDocumentsChanged((channels) => {
if (!channels.includes('files')) return;
if (pushFlushTimer !== null) return;
pushFlushTimer = setTimeout(() => {
pushFlushTimer = null;
requestRefresh();
}, PUSH_REFRESH_COALESCE_MS);
});
return () => {
if (pushFlushTimer !== null) clearTimeout(pushFlushTimer);
scheduler.dispose();
window.removeEventListener('focus', handleResume);
window.removeEventListener('visibilitychange', handleResume);
unsubscribe();
documentTeardownRef.current?.uninstall();
documentTeardownRef.current = null;
};
}, []);
const pages = asTargetNamespace('document', mergePageSets(serverPages, optimisticPages));
const pageTitles = mergePageTitles(serverPageTitles, optimisticPages);
const pageMeta: ReadonlyMap<string, PageMeta> = serverPageMeta;
const assetPaths = asTargetNamespace('file', serverAssetPaths);
const filePaths = asTargetNamespace('file', serverFilePaths);
const folderPaths = createTargetNamespace('folder', [
...deriveKnownFolderPaths(pages),
...serverFolderPaths,
]);
const pagesBySlug = buildPagesBySlugIndex(pages, toWikiLinkSlug);
const pagesByBasename = buildPagesByBasenameIndex(pages, toWikiLinkSlug);
const pageIcons = buildPageIconsIndex(serverPageMeta);
useEffect(() => {
setPageListCache({
pages,
folderPaths,
pagesBySlug,
pagesByBasename,
assetPaths,
filePaths,
pageIcons,
});
}, [pages, folderPaths, pagesBySlug, pagesByBasename, assetPaths, filePaths, pageIcons]);
return (
<PageListContext
value={{
pages,
pagesBySlug,
pagesByBasename,
pageTitles,
pageMeta,
folderPaths,
assetPaths,
filePaths,
loading,
error,
refetch,
addPage,
}}
>
{children}
</PageListContext>
);
}
export function usePageList(): PageListContextValue {
const ctx = use(PageListContext);
if (!ctx) {
throw new Error('usePageList must be used within <PageListProvider />');
}
return ctx;
}
export function useOptionalPageList(): PageListContextValue | null {
return use(PageListContext);
}