Improve package readme and faq.

Author: koculu

frontend/purestack.studio/index.mdx

@@ -563,10 +563,11 @@ card.<span class="syntax-blue">toCSS</span>()</code></pre>
       RegorApp or PageScript. PureStack bundles that entry point and its
       dependencies for the browser.
     </StudioFaq>
-    <StudioFaq title="Is this React MDX?">
-      PureStack uses Regor MDX: Markdown with Regor components and directives.
-      You can use the familiar .mdx extension or the explicit .rmdx extension.
-      React components are not interchangeable with Regor components.
+    <StudioFaq title="Can I use the same components in pages and apps?">
+      Yes. Regor renders components and directives in MDX to static HTML during
+      the build, and powers interactive apps in the browser. Your own components
+      can work in both places; browser apps register the built-in and custom
+      components they use. <a href="/guides/regor/">See the Regor guide</a>.
     </StudioFaq>
     <StudioFaq title="Do I need a particular backend or host?">
       No. PureStack produces static HTML, CSS, and browser assets that you can

packages/ts-common/README.md

@@ -1 +1,10 @@
 # @purestack/ts-common
+
+Shared TypeScript contracts for PureStack's site generator, components, and page
+scripts. This package defines site configuration, page frontmatter, navigation,
+logos, templates, and the rendering context so those packages agree on the same
+shapes.
+
+Import types such as `SiteConfig`, `PageFrontmatter`, and `TsSsgContext` when
+building a custom integration. The runtime exports `resolveTsSsgContext` and
+`tryResolveTsSsgContext` find the site context in a Regor component.

packages/ts-components/README.md

@@ -1,3 +1,10 @@
 # @purestack/ts-components
 
-TypeScript-first component primitives for PureStack.
+PureStack's built-in Regor components for pages and app interfaces. The library
+includes layout, navigation, forms, charts, dialogs, and content components used
+by the static site generator and available to custom renderers.
+
+`defineComponents(getSvgIcon)` assembles the component set, and
+`registerStyles()` adds its styles to PureStack's theme builder. Individual
+component definitions and style registration functions are also exported when
+you need a smaller selection.

packages/ts-components/src/standard/topBar/topBar.test.ts

@@ -20,7 +20,7 @@ describe('TopBar rendering', () => {
     const cleanupDom = createDom(
       '<html><body><div id="app"></div></body></html>',
     )
-    const logoComponent = ref<string | undefined>(undefined)
+    const logoComponent = ref<string | null>(null)
     const app = createApp(
       {
         components: {

packages/ts-minidom/README.md

@@ -1,3 +1,9 @@
 # @purestack/ts-minidom
 
-Minimal DOM implementation extracted from PureStack for server-side rendering and tests.
+A small DOM implementation used to render Regor components in Node.js. It
+provides HTML parsing and the document and element APIs needed by PureStack's
+server-side renderer and component tests.
+
+Use `parseHtml` or `parseFragment` to work with a document directly. `createDom`
+temporarily installs DOM globals and returns a cleanup function; call that
+function after rendering to restore the previous globals.

packages/ts-page-scripts/README.md

@@ -1,3 +1,9 @@
 # @purestack/ts-page-scripts
 
-Shared inline page-script builders and embedded browser runtimes for PureStack.
+Browser behavior for PureStack's generated pages. The exported builders return
+inline JavaScript for theme switching, consent, navigation, menus, tabs,
+dialogs, search, and other page features.
+
+The site generator uses these builders when it adds interactive components to
+static HTML. The package also exports TypeScript types for the browser APIs
+exposed by those scripts, such as `TsSsgTabsApi` and `TsSsgModalApi`.

packages/ts-render/README.md

@@ -1 +1,8 @@
 # @purestack/ts-render
+
+Server-side rendering for PureStack's Regor components. `renderApp` takes HTML,
+a component set, and a `TsSsgContext`, then returns rendered HTML with any
+required component scripts attached.
+
+`componentRegistry` lets custom build pipelines register components by name.
+The site generator uses this package to turn page markup into static output.

packages/ts-style/README.md

@@ -1 +1,9 @@
 # @purestack/ts-style
+
+Theme and style infrastructure for PureStack sites and components. It provides
+light and dark palettes, CSS variables, theme skins, breakpoints, layout tokens,
+and utilities for building scoped styles with `@purestack/ts-css`.
+
+Use `themes` and `registerSkin` to configure a site's palette, or
+`styleBuilder` to collect and render CSS for a theme. PureStack's component
+library and site generator use these same exports.

packages/ts-util-node/README.md

@@ -1,3 +1,8 @@
 # @purestack/ts-util-node
 
-Node-only utility helpers for PureStack.
+File path helpers for PureStack's Node.js build tools. `ensureDir(filePath)`
+creates the parent directory for a file, and `replaceExt(filePath, newExt)`
+returns the path with a different extension.
+
+Use this package in build scripts and other Node.js code. Browser-safe helpers
+live in `@purestack/ts-util`.

packages/ts-util/README.md

@@ -1,6 +1,8 @@
 # @purestack/ts-util
 
-Shared utility helpers extracted from PureStack.
+Small, browser-safe helpers shared across PureStack packages. Exports include
+HTML escaping, object merging, value and type checks, caching, and URL and asset
+path handling.
 
-This package should stay browser-safe. Do not add Node-only dependencies such as
-`node:path`, `node:fs`, or other `node:` imports here.
+Use `escapeHtml`, `merge`, `normalizeBasePath`, or the other named exports when
+building on PureStack without pulling in Node.js APIs.