@lickle/docs 0.0.0-dev.1

package/src/ui/context/components.tsx

@@ -0,0 +1,103 @@
+import { createContext, createMemo, Show, useContext } from 'solid-js'
+import type { Accessor, Component } from 'solid-js'
+import type { JSX } from 'solid-js/jsx-runtime'
+import { Dynamic } from 'solid-js/web'
+
+import type { Types } from '../context/index.ts'
+import type { t } from '../../_lib/index.ts'
+
+const ComponentsCtx = createContext<Accessor<Components>>(() => ({}))
+
+/**
+ * Provide a component registry to descendants. When nested inside another
+ * `<ComponentsProvider>` the inner value is shallow-merged onto the outer one,
+ * so a wrapper preset can establish defaults that an app extends without
+ * losing the outer's entries.
+ */
+export const ComponentsProvider = (props: { value?: Components; children: JSX.Element }) => {
+  const outer = useContext(ComponentsCtx)
+  const merged = createMemo<Components>(() => ({ ...outer(), ...window.lickle.components[0](), ...props.value }))
+  return <ComponentsCtx.Provider value={merged}>{props.children}</ComponentsCtx.Provider>
+}
+
+/** Read the active (already-merged) component registry. */
+export const useComponents = (): Accessor<Components> => useContext(ComponentsCtx)
+
+/**
+ * Build a slot dispatcher in one line: look up the override under `key`,
+ * forward `Default` so it can decorate, otherwise render the default. The
+ * override and default share the same prop shape — that's what the
+ * `WithDefault<P>` wrapper in {@link Slots} pins down.
+ */
+export const createSlot =
+  <K extends keyof Components>(
+    key: K,
+    Default: Component<t.Compute<Omit<Params<Components[K]>[0], 'Default'>>>,
+  ): Component<t.Compute<Omit<Params<Components[K]>[0], 'Default'>>> =>
+  (props) => {
+    const slots = useComponents()
+    const override = createMemo(() => slots()[key] as Component<any> | undefined)
+    return (
+      <Show when={override()} fallback={<Default {...(props as any)} />} keyed>
+        {(Override) => <Dynamic component={Override} {...(props as any)} Default={Default} />}
+      </Show>
+    )
+  }
+
+type Params<T> = T extends (...args: infer P) => any ? P : never
+
+type WithDefault<P extends Record<string, any>> = P & { Default: Component<P> }
+
+export type DeclarationProps<K extends keyof Types.DeclarationMap> = WithDefault<{
+  decl: Types.DeclarationMap[K]
+}>
+
+type PageProps = { decl: Types.Declaration; route: Types.RouteNode<'declaration' | 'module'> }
+
+export type SlotComponent<K extends keyof Components> = Components[K]
+/**
+ * Slot override signatures. Every slot receives `Default` typed to the
+ * stock component's props so the override can decorate (`<Default {...p} />`
+ * plus extras) instead of replacing wholesale.
+ */
+export interface Components {
+  home?: Component<WithDefault<{}>>
+  layout?: Component<WithDefault<{ children: JSX.Element }>>
+  header?: Component<WithDefault<{ onMenu?: () => void; onSearch?: () => void }>>
+  sidebar?: Component<WithDefault<{ onNavigate?: () => void; class?: string }>>
+
+  // Page slots
+  page?: Component<WithDefault<PageProps>>
+  'page.markdown'?: Component<WithDefault<{ route: Types.RouteNode<'markdown'> }>>
+  'page.header'?: Component<WithDefault<PageProps>>
+  'page.header.breadcrumb'?: Component<WithDefault<{ id: number }>>
+  'page.source'?: Component<WithDefault<{ sources?: Types.Source[] }>>
+  'page.references'?: Component<WithDefault<{ id: number }>>
+
+  // Declaration page slots
+  declaration?: Component<WithDefault<{ decl: Types.Declaration }>>
+  'declaration.function'?: Component<DeclarationProps<'function'>>
+  'declaration.variable'?: Component<DeclarationProps<'variable'>>
+  'declaration.type-alias'?: Component<DeclarationProps<'type-alias'>>
+  'declaration.class'?: Component<DeclarationProps<'class'>>
+  'declaration.interface'?: Component<DeclarationProps<'interface'>>
+  'declaration.enum'?: Component<DeclarationProps<'enum'>>
+  'declaration.module'?: Component<DeclarationProps<'module'>>
+  'declaration.namespace'?: Component<DeclarationProps<'namespace'>>
+
+  comment?: Component<WithDefault<{ comment?: Types.Comment; class?: string }>>
+  'comment.parameters'?: Component<WithDefault<{ tags: Types.CommentTagMap['@param'][] }>>
+  'comment.properties'?: Component<WithDefault<{ tags: Types.CommentTagMap['@property'][] }>>
+
+  tag?: Component<WithDefault<{ tag: Types.CommentTag }>>
+  'tag.returns'?: Component<WithDefault<{ tag: t.Compute<Types.CommentTagMap['@returns']> }>>
+  'tag.throws'?: Component<WithDefault<{ tag: Types.CommentTagMap['@throws'] }>>
+  'tag.type'?: Component<WithDefault<{ tag: Types.CommentTagMap['@type'] }>>
+  'tag.satisfies'?: Component<WithDefault<{ tag: Types.CommentTagMap['@satisfies'] }>>
+  'tag.example'?: Component<WithDefault<{ tag: Types.CommentTagMap['@example'] }>>
+  'tag.see'?: Component<WithDefault<{ tag: Types.CommentTagMap['@see'] }>>
+  'tag.template'?: Component<WithDefault<{ tag: Types.CommentTagMap['@template'] }>>
+  'tag.augments'?: Component<WithDefault<{ tag: Types.CommentTagMap['@augments'] }>>
+  'tag.implements'?: Component<WithDefault<{ tag: Types.CommentTagMap['@implements'] }>>
+  'tag.*'?: Component<WithDefault<{ tag: Types.CommentTag }>>
+}

package/src/ui/context/global.ts

@@ -0,0 +1,33 @@
+import { createSignal, type Signal } from 'solid-js'
+
+import type { Types } from '../context/index.ts'
+import type { Components } from './components.tsx'
+
+declare global {
+  interface Lickle {
+    components: Signal<Components>
+    json: Signal<Types.ProjectJson | null>
+    rendered: Signal<boolean>
+  }
+  interface Window {
+    lickle: Lickle
+  }
+}
+
+if (typeof window !== 'undefined') {
+  window.lickle = {
+    components: createSignal<Components>({}),
+    json: createSignal<Types.ProjectJson | null>(null),
+    rendered: createSignal<boolean>(false),
+  }
+}
+
+export const getComponents = () => window.lickle.components[0]()
+export const setComponents = (components: Partial<Components>) =>
+  window.lickle.components[1]({ ...window.lickle.components[0](), ...components })
+
+export const getJson = () => window.lickle.json[0]()
+export const setJson = (json: Types.ProjectJson | null) => window.lickle.json[1](json)
+
+export const getRendered = () => window.lickle.rendered[0]()
+export const setRendered = (rendered: boolean) => window.lickle.rendered[1](rendered)

package/src/ui/context/index.ts

@@ -0,0 +1,4 @@
+export * from './project/index.tsx'
+export * from './markup/index.tsx'
+export * from './components.tsx'
+export * from './theme.tsx'

package/src/ui/context/markup/index.tsx

@@ -0,0 +1,39 @@
+import { createContext, createMemo, createResource, useContext } from 'solid-js'
+import type { JSX } from 'solid-js/jsx-runtime'
+import type { Marked } from 'marked'
+
+import { highlighter, type Highlighter, type CodeToHtmlOptions } from './shiki.ts'
+import { useProject } from '../project/index.tsx'
+import { buildMarked } from './markdown.ts'
+
+export * from './util.ts'
+
+export type { Highlighter, CodeToHtmlOptions }
+
+const H = highlighter()
+
+type MarkupContext = {
+  promise: Promise<Highlighter>
+  highlighter: () => Highlighter | undefined
+  marked: () => Marked | undefined
+}
+const Context = createContext<MarkupContext>()
+
+export const MarkupProvider = (props: { children: JSX.Element }) => {
+  const project = useProject()
+  const lookup = (name: string) => project().routeByName(name)?.slug
+  const [h] = createResource(async () => await H)
+  const marked = createMemo(() => buildMarked(h(), lookup))
+  return <Context.Provider value={{ promise: H, highlighter: () => h(), marked }}>{props.children}</Context.Provider>
+}
+
+export const useMarkup = (): MarkupContext => {
+  const ctx = useContext(Context)
+  if (!ctx) throw new Error('useMarkup must be used within a <MarkupProvider>')
+  return ctx
+}
+
+export const useCodeToHtml = (p: { code: string; lang?: string; structure?: 'inline' | 'classic' }) => {
+  const markup = useMarkup()
+  return createMemo(() => markup.highlighter()?.codeToHtml({ ...p, text: p.code, markdown: true }))
+}

package/src/ui/context/markup/markdown.ts

@@ -0,0 +1,37 @@
+import { Marked } from 'marked'
+
+import type { Highlighter } from './shiki.ts'
+import { langOf } from './util.ts'
+
+export const buildMarked = (h: Highlighter | undefined, lookup?: (raw: string) => string | undefined) => {
+  const m = new Marked({
+    gfm: true,
+    breaks: false,
+    renderer: {
+      code({ text, lang }) {
+        const language = langOf(lang)
+        if (h && language !== 'text') {
+          try {
+            return h.codeToHtml({ text, lang: language })
+          } catch {
+            /* fall through */
+          }
+        }
+        return `<pre class="codeblock"><code>${escape(text)}</code></pre>`
+      },
+      codespan({ text }) {
+        if (lookup && ID.test(text)) {
+          const slug = lookup(text)
+          if (slug) return `<a href="/${slug}" class="codelink"><code>${text}</code></a>`
+        }
+        return `<code>${text}</code>`
+      },
+    },
+  })
+  return m
+}
+
+const escape = (s: string) =>
+  s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
+
+const ID = /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/

package/src/ui/context/markup/shiki.ts

@@ -0,0 +1,72 @@
+import type { HighlighterCore } from 'shiki/core'
+
+import { extractCodeBlocks } from './util.ts'
+
+export type CodeToHtmlOptions = {
+  text: string
+  lang?: string
+  structure?: 'inline' | 'classic'
+  markdown?: boolean
+}
+
+export type Highlighter = { codeToHtml: (options: CodeToHtmlOptions) => string }
+
+export const highlighter = async (): Promise<Highlighter> => {
+  const h = await getHighlighter()
+  const codeToHtml = (options: CodeToHtmlOptions) => {
+    const opts = {
+      lang: options.lang ?? 'ts',
+      themes: { light: 'github-light', dark: 'github-dark' },
+      defaultColor: false,
+      structure: options.structure,
+    } as const
+
+    if (options.markdown) {
+      const extracted = extractCodeBlocks(options.text)?.[0]
+      if (extracted) {
+        if (!h || !extracted) return ''
+        const text = extracted.code ?? options.text
+        const lang = extracted.lang ?? options.lang ?? 'ts'
+        return h.codeToHtml(text, { ...opts, lang: lang })
+      }
+    }
+    return h.codeToHtml(options.text, opts)
+  }
+  return { codeToHtml }
+}
+
+/**
+ * Fine-grained Shiki bundle: only the langs/themes below are emitted as chunks.
+ * Importing the default `shiki` entry would code-split every grammar and theme.
+ */
+export const getHighlighter = (): Promise<HighlighterCore> => {
+  if (!highlighterPromise) highlighterPromise = buildHighlighter()
+  return highlighterPromise
+}
+let highlighterPromise: Promise<HighlighterCore> | null = null
+
+const buildHighlighter = (): Promise<HighlighterCore> => {
+  return Promise.all([
+    import('shiki/core'),
+    import('shiki/engine/javascript'),
+    import('shiki/themes/github-light.mjs'),
+    import('shiki/themes/github-dark.mjs'),
+    Promise.all([
+      import('shiki/langs/typescript.mjs'),
+      import('shiki/langs/tsx.mjs'),
+      import('shiki/langs/javascript.mjs'),
+      import('shiki/langs/jsx.mjs'),
+      import('shiki/langs/json.mjs'),
+      import('shiki/langs/bash.mjs'),
+      import('shiki/langs/html.mjs'),
+      import('shiki/langs/css.mjs'),
+      import('shiki/langs/markdown.mjs'),
+    ]),
+  ]).then(([core, js, light, dark, langs]) =>
+    core.createHighlighterCore({
+      engine: js.createJavaScriptRegexEngine(),
+      themes: [light.default, dark.default],
+      langs: langs.map((m) => m.default),
+    }),
+  )
+}

package/src/ui/context/markup/util.ts

@@ -0,0 +1,20 @@
+const CODE_BLOCK_RE = /```([^\n]*)\n([\s\S]*?)```/g
+export const extractCodeBlocks = (input: string): { lang: string; code: string }[] => [
+  ...(input?.matchAll(CODE_BLOCK_RE)?.map((m) => ({ lang: m[1]!, code: m[2]! })) ?? []),
+]
+
+export const firstCodeBlock = (input: string): { lang: string; code: string } =>
+  extractCodeBlocks(input)?.[0] ?? { lang: '', code: input }
+
+export const getUnfencedCode = (code: string) => firstCodeBlock(code).code
+
+const LANGS = ['ts', 'tsx', 'js', 'jsx', 'json', 'bash', 'html', 'css', 'md']
+export const langOf = (info: string | undefined) => {
+  const raw = (info ?? '').trim().split(/\s+/)[0]?.toLowerCase() ?? ''
+  if (!raw) return 'text'
+  if (LANGS.includes(raw)) return raw
+  if (raw === 'sh' || raw === 'zsh') return 'bash'
+  if (raw === 'typescript') return 'ts'
+  if (raw === 'javascript') return 'js'
+  return 'text'
+}

package/src/ui/context/project/index.tsx

@@ -0,0 +1,47 @@
+import { createContext, createMemo, useContext, type Accessor } from 'solid-js'
+import type { JSX } from 'solid-js/jsx-runtime'
+
+import type { ProjectJson } from './types.ts'
+
+import { ComponentsProvider, type Components } from '../components.tsx'
+import { createProject } from './indexed.ts'
+
+import * as T from './types.ts'
+export * as Types from './types.ts'
+
+const ProjectCtx = createContext<Accessor<T.Project>>()
+
+export type ProjectProviderProps = {
+  children: JSX.Element
+  json: Accessor<ProjectJson>
+  /** Component overrides — pages, tags, slots, member sections. */
+  components?: Components
+}
+
+export const ProjectProvider = (props: ProjectProviderProps) => {
+  const bag = createMemo<T.Project>(() => createProject(props.json()))
+  return (
+    <ComponentsProvider value={props.components}>
+      <ProjectCtx.Provider value={bag}>{props.children}</ProjectCtx.Provider>
+    </ComponentsProvider>
+  )
+}
+
+export const useProject = (): Accessor<T.Project> => {
+  const fn = useContext(ProjectCtx)
+  if (!fn) throw new Error('useProject must be used within <ProjectProvider>')
+  return fn
+}
+
+const DeclarationIdContext = createContext<Accessor<number | undefined>>(() => undefined)
+
+/**
+ * Scope a subtree to a reflection id so nested `<Comment>`s pass it to tag
+ * handlers. The id is exposed as a reactive accessor so consumers re-track
+ * when the surrounding route swaps to a new declaration.
+ */
+export const DeclarationScope = (props: { id: number; children: JSX.Element }) => (
+  <DeclarationIdContext.Provider value={() => props.id}>{props.children}</DeclarationIdContext.Provider>
+)
+
+export const useDeclarationId = (): Accessor<number | undefined> => useContext(DeclarationIdContext)

package/src/ui/context/project/indexed.ts

@@ -0,0 +1,52 @@
+import type { ProjectJson, RouteNode } from '../../../core/project/index.ts'
+import * as Types from './types.ts'
+
+export const createProject = (json: ProjectJson): Types.Project => {
+  const _byId = new Map<number, Types.Declaration>()
+  const _bySlug = new Map<string, Types.Declaration>()
+  const _routesById = new Map<number, RouteNode>()
+  const _routesBySlug = new Map<string, RouteNode>()
+  const _slugByName = new Map<string, RouteNode>()
+
+  const sourceLink = (src: Types.Source) => {
+    if (!json.repository?.fileUrl) return undefined
+    return json.repository.fileUrl.replace('{PATH}', src.file).replace('{LINE}', src.line.toString())
+  }
+
+  for (const declaration of json.declarations) {
+    _byId.set(declaration.id, declaration)
+  }
+
+  const indexRoute = (r: RouteNode) => {
+    _routesBySlug.set(r.slug, r)
+    // Markdown pages carry no declaration id, so they only resolve by slug.
+    if (r.page.kind !== 'markdown') {
+      _bySlug.set(r.slug, _byId.get(r.page.id)!)
+      _routesById.set(r.page.id, r)
+      const name = _byId.get(r.page.id)?.name
+      if (name && !_slugByName.has(name)) _slugByName.set(name, r)
+      _slugByName.set(r.page.qualified, r)
+    }
+    for (const child of r.children) indexRoute(child)
+  }
+
+  for (const route of json.routes) indexRoute(route)
+
+  const byId = (id: number): Types.Declaration | undefined => _byId.get(id)
+  const bySlug = (slug: string): Types.Declaration | undefined => _bySlug.get(slug)
+  const routeForId = (id: number): RouteNode | undefined => _routesById.get(id)
+  const routeForSlug = (slug: string): RouteNode | undefined => _routesBySlug.get(slug)
+  const routeByName = (name: string): RouteNode | undefined => _slugByName.get(name)
+  const p: Types.Project = json as Types.Project
+
+  hide(p, 'byId', byId)
+  hide(p, 'bySlug', bySlug)
+  hide(p, 'routeForId', routeForId)
+  hide(p, 'routeForSlug', routeForSlug)
+  hide(p, 'routeByName', routeByName)
+  hide(p, 'sourceLink', sourceLink)
+  return p
+}
+
+const hide = <T, K extends keyof T>(obj: T, key: K, value: T[K]) =>
+  Object.defineProperty(obj, key, { value, enumerable: false, configurable: true })

package/src/ui/context/project/types.ts

@@ -0,0 +1,14 @@
+import type { ProjectJson, RouteNode } from '../../../core/project/types.ts'
+import type { Declaration, Source } from '../../../core/reflect/types.ts'
+
+export interface Project extends ProjectJson {
+  byId(id: number): Declaration | undefined
+  bySlug(slug: string): Declaration | undefined
+  routeByName(name: string): RouteNode | undefined
+  routeForId(id: number): RouteNode | undefined
+  routeForSlug(slug: string): RouteNode | undefined
+  sourceLink(src: Source): string | undefined
+}
+
+export type * from '../../../core/project/types.ts'
+export type * from '../../../core/reflect/types.ts'

package/src/ui/context/theme.tsx

@@ -0,0 +1,45 @@
+import { createContext, createSignal, onMount, useContext } from 'solid-js'
+import type { JSX } from 'solid-js/jsx-runtime'
+
+export type ThemeMode = 'light' | 'dark' | 'system'
+const STORAGE_KEY = 'lickle-docs-theme'
+
+type ThemeCtx = {
+  mode: () => ThemeMode
+  setMode: (m: ThemeMode) => void
+}
+
+const Ctx = createContext<ThemeCtx>()
+
+const read = (): ThemeMode => {
+  if (typeof localStorage === 'undefined') return 'system'
+  const v = localStorage.getItem(STORAGE_KEY)
+  return v === 'light' || v === 'dark' ? v : 'system'
+}
+
+const apply = (m: ThemeMode) => {
+  const el = document.documentElement
+  if (m === 'system') delete el.dataset['theme']
+  else el.dataset['theme'] = m
+}
+
+export const ThemeProvider = (props: { children: JSX.Element }) => {
+  const [mode, set] = createSignal<ThemeMode>(read())
+
+  onMount(() => apply(mode()))
+
+  const setMode = (m: ThemeMode) => {
+    if (m === 'system') localStorage.removeItem(STORAGE_KEY)
+    else localStorage.setItem(STORAGE_KEY, m)
+    set(m)
+    apply(m)
+  }
+
+  return <Ctx.Provider value={{ mode, setMode }}>{props.children}</Ctx.Provider>
+}
+
+export const useTheme = (): ThemeCtx => {
+  const ctx = useContext(Ctx)
+  if (!ctx) throw new Error('useTheme must be used within a <ThemeProvider>')
+  return ctx
+}

package/src/ui/hooks/index.ts

@@ -0,0 +1,116 @@
+import { createMemo, type Accessor } from 'solid-js'
+
+import { createSearchEngine, type SearchEngine } from '../util/search.ts'
+import { useProject, type Types } from '../context/index.ts'
+import { commentSummaryText } from '../util/comment.ts'
+
+// ============================================================================
+// SELECTOR HOOKS
+// Thin readers over the project bag. Components should reach for these instead
+// of pulling `project` apart directly.
+// ============================================================================
+
+/**
+ * Slug accessors keyed two ways. `byId` is the id-driven path used by render
+ * code; `byName` powers `{@link Foo}` / `<code>Foo</code>` resolution (short
+ * names and qualified names both resolve via the project's name index).
+ */
+export const useSlugFor = () => {
+  const project = useProject()
+  return {
+    byId: (id: number): string | undefined => project().routeForId(id)?.slug,
+    byName: (name: string): string | undefined => project().routeByName(name)?.slug,
+  }
+}
+
+// ============================================================================
+// REFERENCES
+// "Used in" rows, materialized from each page's `referencedIn` id list.
+// ============================================================================
+
+export interface ReferenceRow {
+  decl: Types.Declaration
+  slug: string
+  /** Everything before the final dot of the qualified name. Empty for top-level symbols. */
+  module: string
+  name: string
+  qualified: string
+  summary: string
+}
+
+export const useReferences = (id: () => number): Accessor<ReferenceRow[]> => {
+  const project = useProject()
+  return createMemo(() => buildReferenceRows(project(), id()))
+}
+
+const buildReferenceRows = (project: Types.Project, id: number): ReferenceRow[] => {
+  const route = project.routeForId(id)
+  if (!route || route.page.kind === 'markdown') return []
+
+  const seen = new Set<number>()
+  const out: ReferenceRow[] = []
+  for (const refId of route.page.referencedIn) {
+    if (refId === id || seen.has(refId)) continue
+    seen.add(refId)
+    const refRoute = project.routeForId(refId)
+    const decl = project.byId(refId)
+    if (!refRoute || refRoute.page.kind === 'markdown' || !decl) continue
+    const qualified = refRoute.page.qualified
+    const dot = qualified.lastIndexOf('.')
+    out.push({
+      decl,
+      slug: refRoute.slug,
+      module: dot < 0 ? '' : qualified.slice(0, dot),
+      name: dot < 0 ? qualified : qualified.slice(dot + 1),
+      qualified,
+      summary: commentSummaryText(decl.comment),
+    })
+  }
+  return out.sort((a, b) => a.qualified.localeCompare(b.qualified))
+}
+
+// ============================================================================
+// SEARCH
+// `createSearchEngine` is async (Orama indexing). Cached per project so the
+// palette pays the cost once per session, even if it opens and closes.
+// ============================================================================
+
+const searchCache = new WeakMap<object, Promise<SearchEngine>>()
+
+/**
+ * Returns a thunk that builds (or returns the cached) search engine for the
+ * current project. Callers wrap the thunk in their own resource/effect.
+ */
+export const useSearch = (): (() => Promise<SearchEngine>) => {
+  const project = useProject()
+  return () => buildSearch(project())
+}
+
+const buildSearch = (project: Types.Project): Promise<SearchEngine> => {
+  const cached = searchCache.get(project)
+  if (cached) return cached
+  const p = createSearchEngine(project)
+  searchCache.set(project, p)
+  return p
+}
+
+export const useCommentMarkdown = (comment: () => Types.Comment) => {
+  const slugs = useSlugFor()
+  const slugOf = (name: string) => slugs.byName(name)
+  return createMemo(() => commentToMarkdown(comment(), slugOf))
+}
+
+const commentToMarkdown = (comment: Types.Comment, slugOf: (name: string) => string | undefined): string => {
+  let out = ''
+  for (const p of comment.parts) {
+    if (p.kind === 'text') {
+      out += p.text
+      continue
+    }
+    const label = p.text ?? p.target
+    const slug = slugOf(p.target)
+    const display = p.style === 'code' ? `\`${label}\`` : label
+    out += slug ? `[${display}](/${slug})` : display
+  }
+  return out
+}

package/src/ui/index.ts

@@ -0,0 +1,4 @@
+export * from './components/index.ts'
+export * from './context/index.ts'
+export * from './renderer.tsx'
+export * from './App.tsx'

package/src/ui/renderer.tsx

@@ -0,0 +1,31 @@
+import { createMemo, type Accessor } from 'solid-js'
+import { render } from 'solid-js/web'
+
+import type { Components } from './context/components.tsx'
+import { App } from './App.tsx'
+
+import { getJson, getComponents, setComponents } from './context/global.ts'
+import type { Types } from './context/index.ts'
+
+export const renderApp = (props?: {
+  json?: Accessor<Types.ProjectJson | null> | Types.ProjectJson | null
+  components?: Accessor<Components> | Components
+  root?: HTMLElement
+}) => {
+  const json = createMemo(() => {
+    const j = typeof props?.json === 'function' ? props?.json() : (props?.json ?? null)
+    if (!j) return getJson()
+    return j
+  })
+
+  const components = createMemo(() => {
+    const c = typeof props?.components === 'function' ? props?.components() : (props?.components ?? null)
+    if (!c) return getComponents()
+    return c
+  })
+
+  render(() => <App json={json} components={components} />, props?.root ?? document.getElementById('root')!)
+}
+
+export const registerComponent = <K extends keyof Components>(key: K, Component: Components[K]) =>
+  setComponents({ [key]: Component })

package/src/ui/util/comment.ts

@@ -0,0 +1,12 @@
+import type { Types } from '../context/index.ts'
+
+/** Single-line plain-text preview of a comment. Used by listings/cards. */
+export const commentSummaryText = (comment: Types.Comment | undefined): string => {
+  if (!comment) return ''
+  let out = ''
+  for (const p of comment.parts) {
+    if (p.kind === 'text') out += p.text
+    else out += p.text ?? p.target
+  }
+  return out.trim()
+}