@webring-kit/core

Framework-independent core utilities for Webring Kit.

@webring-kit/core contains the shared logic used by the Web Components, framework adapters, and CLI. It does not render UI and can be used from Node.js tooling or browser bundlers.

What it provides

• Ring manifest validation.
• URL normalization and safe URL handling.
• Current-site resolution.
• Previous, next, and random site navigation.
• Ring source adapters for JSON URLs, GitHub contents, and inline manifests.
• Memory and browser cache helpers.
• TypeScript types for ring manifests and sites.

Install

pnpm add @webring-kit/core

npm install @webring-kit/core

Basic usage

import {
  NavigationService,
  RingValidator,
  normalizeSiteUrl
} from "@webring-kit/core";

const manifest = {
  version: 1,
  id: "indie-devs",
  name: "Indie Devs Webring",
  sites: [
    {
      id: "alice",
      title: "Alice's Notes",
      url: "https://alice.example.com"
    },
    {
      id: "bob",
      title: "Bob Builds",
      url: "https://bob.example.com"
    }
  ]
};

const ring = new RingValidator().validate(manifest);
const navigation = new NavigationService(ring);

const current = navigation.resolveCurrentSite("https://alice.example.com");
const next = navigation.getNextSite("https://alice.example.com");
const previous = navigation.getPreviousSite("https://alice.example.com");
const normalized = normalizeSiteUrl("https://alice.example.com/");

Runtime compatibility

This package is ESM-only.

It is intended for:

• Node.js tooling.
• Browser bundlers such as Vite, Next.js, Astro, and SvelteKit.
• Internal use by @webring-kit/element, @webring-kit/react, @webring-kit/next, and @webring-kit/cli.

Security model

The core validator should reject unsupported URL schemes and malformed manifests. Consumer code should still treat ring manifests as untrusted external data and render manifest text with safe text APIs rather than HTML injection.

Related packages

• @webring-kit/element for native Web Components.
• @webring-kit/react for React wrappers.
• @webring-kit/next for Next.js helpers.
• @webring-kit/cli for manifest validation and maintenance commands.
• @webring-kit/schemas for JSON Schema files.