White Noise website
Marketing and documentation site for White Noise, built with SvelteKit.
Agent-readable responses, discovery formats, deployment checks and the applicability of service-specific recommendations are documented in Agent access.
Development
Use Node 22 (22.18 or newer) and Bun 1.4.2, matching CI and the Vercel runtime.
bun install --frozen-lockfile
bun run dev
Dependency installs are guarded against freshly published compromises. bunfig.toml makes Bun skip package versions published within the last three days whenever it resolves a new version; locked versions still install. To take an urgent security fix sooner, review the release and run that one install or update with --minimum-release-age=0. trustedDependencies is empty, so no dependency install script runs; trust a package only after reviewing its script. CI and Vercel install with --frozen-lockfile. CI pins GitHub Actions to full commit SHAs with version comments and checks out without persisted credentials. Dependabot opens weekly pull requests for Bun packages and GitHub Actions after a seven-day cooldown, grouping minor and patch updates; major package updates arrive separately, except @types/node, which stays on the Node 22 runtime's major version.
Development and production preview servers listen on the local network for phone testing. Open the Network URL printed by Vite on a phone connected to the same Wi-Fi. Keep the server running during review and use the default scripts rather than overriding the host with 127.0.0.1.
Quality checks
bun run test
bun run lint:write
bun run format
bun run check
bun run build
Site structure and maintenance
- Navigation destinations and active-page rules live in
src/lib/navigation.ts, with guide paths and sections in src/lib/documentation-navigation.ts. The header and closing Download section live in src/lib/components/site and are rendered once by the root layout. Shared UI primitives live in src/lib/components/system.
- Appearance follows the device by default, with a persistent light/dark icon toggle in the top navigation. The small
static/theme.js bootstrap applies saved choices before page paint; the design-system catalog owns both palettes.
src/lib/design-system/README.md documents the active tokens, typography and component contracts. /design-system is the noindex reference, omitted from navigation and the sitemap. Run bun run tokens:generate after editing a catalog and include its generated CSS and runtime constants with the source.- Homepage features live in
src/lib/content/homepage.ts; FAQ pages, structured data and text exports share src/lib/content/faqs.ts. The short Agents, Build and Marmot guides use local Markdown in src/lib/content; full upstream documentation remains on GitHub. Legacy documentation URLs retain their redirects.
- Blog posts and canary attestations come from Nostr. Keep their loaders, sanitization, cache behavior and signed data intact. The privacy policy source is
src/lib/content/privacy-policy.md.
- Generated exports and temporary browser evidence belong in ignored
output/ or tmp/ directories. They are not production assets. Superseded design explorations and screenshots remain recoverable from Git history.
- The site uses the Vercel adapter.
bun run ci runs the release checks locally; publishing still requires explicit authorization.
Production behavior
Marketing pages, the FAQ, and the Agents, Build and Marmot guides are pre-rendered. The shared docs route uses an explicit Marmot README entry with prerender = "auto"; other documentation URLs remain server redirects and do not initialize the guide renderer. The legacy .md page URL serves HTML by default through file-specific Build Output MIME metadata, and serves Markdown when explicitly requested; the preview middleware maps it to the generated .html file because SvelteKit preview otherwise infers Markdown MIME from the URL. Blog content, canary attestations and the sitemap also use server routes. No relay access is needed to build static pages. The page shell includes a styled error route; content outages return 503 rather than a misleading 404.
Relay transport lives under src/lib/server. It verifies signatures, author, kind and filters, chooses the newest replaceable event, and closes requests within ten seconds. Requests retain verified partial results. List and article caches coalesce concurrent reads, expire after five minutes, and allow at most one hour of stale blog content after refresh failures. Expired missing-post results are never served as stale content during an outage. Caches are process-local and bounded; they are not persistent storage. Canary data is cached for one minute with no stale-on-error fallback. The page renders the signed statement verbatim, escaped as text.
The content security policy permits same-origin code and the existing analytics.ipf.dev service. Inline style attributes remain allowed for measured artwork and the live design reference; inline executable scripts require SvelteKit's generated hashes/nonces. Blog images may use HTTP(S) origins. Framing is denied, content sniffing is disabled, and cross-origin referrers are limited. Vercel applies the static-asset headers as well. Keep deployment policy in sync with the local server hooks.
/llms.txt and /llms-full.txt retain their public URLs and are generated from the overview, FAQ and guide sources. They no longer claim to contain full upstream documentation. The sitemap reports article modification dates and does not invent fresh modification dates for static pages.
여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗
