@mosetta/core 0.0.0-stage → 0.0.10

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# @mosetta/core
+
+## 0.0.10
+
+## 0.0.9
+
+## 0.0.8
+
+### Patch Changes
+
+- A project's own tile palette. The registry keeps the palettes a project's site takes tiles from;
+  the factory reads each one's tile host after the platform's, and takes a tile of a host other than
+  the primary only with its integrity. The rule a site's tile hosts merge by lives in
+  `@mosetta/core` (`mergeTileHosts`), so the editor offers the blocks of every tile host of the site
+  by the same rule (`TILE_HOSTS_TOKEN` in `@mosetta/server-action`). The platform's API publishes
+  into `palettes/<brand>` for the members of the project of that namespace, with the palette's stores
+  granted to that one request. `mosetta build --released <descriptor>` leaves out what a platform
+  already holds; `checkPaletteBuild` says what a palette may hold. The CLI's and the build's output
+  speaks the vocabulary: tile palettes, tiles, package tiles.
+
+## 0.0.7
+
+### Patch Changes
+
+- One vocabulary: code is tiles, content is blueprints, running requests is the factory, and a tile and a
+  blueprint made in the factory give a mosaic. A tile is a folder under `tiles/` (was `modules/`) whose
+  files are its sides, each defined with `define<Side>Side` — `defineComponentSide`, `defineEditorSide`,
+  `defineFallbackSide`, `defineRootComponentSide`, `defineServerSide`, `defineSsrSide` (were
+  `define…Module`); `useTile` (was `useModule`), `markInternalTile`, `BlueprintRoot`,
+  `BlueprintNodeRenderer`. `mosetta.json` names the tile `brand` (was `namespace`; a config that still
+  says `namespace` is refused with the word to use). The store connectors' package is `@mosetta/stores`
+  (was `@mosetta/provider`): `IStoreConnector`, `StoreConnectors`, `tileHostsOf`. The server's runner
+  is the factory gate (`@mosetta/server/factoryGate`, was `/runner`). Nothing on the wire moves: tile
+  ids keep `_ns_`, a build keeps `modules/<id>/`, stored JSON keeps its fields.
+
+## 0.0.6
+
+## 0.0.5
+
+## 0.0.4
+
+## 0.0.3
+
+## 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mosetta contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,8 @@
-# Temporary Holding Version
+# @mosetta/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Framework-agnostic models of the mosetta protocol: tile references (`_ns_<brand>_t_<side>_n_<name>_v_<version>`),
+blueprint node trees and pages, routing patterns, languages, the styler and theme models, the rule
+a site's tile hosts merge by (`mergeTileHosts`), and the application error hierarchy.
+
+`@mosetta/core/tsconfig.base.json` is the TypeScript base the protocol's packages and tile palettes
+extend.

package/package.json

@@ -1,6 +1,21 @@
 {
   "name": "@mosetta/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "mosetta core models: tile references, blueprint node trees, pages, the rule a site's tile hosts merge by, and the application error hierarchy. Framework-agnostic.",
+  "version": "0.0.10",
+  "license": "MIT",
+  "type": "commonjs",
+  "exports": {
+    ".": "./src/core.ts",
+    "./tsconfig.base.json": "./tsconfig.base.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "*",
+    "typescript": "*"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  }
 }

package/src/core.ts

@@ -0,0 +1,9 @@
+export * from './models/commonModels';
+export * from './models/pageModels';
+export * from './models/tileHosts';
+export * from './errors/appError';
+export * from './errors/errors';
+export * from './styler';
+export * from './theme';
+export * from './languages';
+export * from './routing';

package/src/errors/appError.ts

@@ -0,0 +1,42 @@
+export interface IWithError {
+  readonly error?: AppError;
+}
+
+export abstract class AppError extends Error {
+  readonly appErrorType: string;
+
+  readonly message: string;
+
+  readonly parentError?: Error;
+
+  static isAppError<T extends AppError>(
+    error: unknown,
+    type: T['appErrorType'],
+  ): error is T {
+    if (error && typeof error === 'object' && 'appErrorType' in error) {
+      return error.appErrorType === type;
+    }
+
+    return false;
+  }
+
+  protected constructor({
+    appErrorType,
+    message = 'app error',
+    parentError,
+  }: {
+    readonly appErrorType: string;
+    readonly message?: string;
+    readonly parentError?: Error;
+  }) {
+    super(`[${appErrorType}] ${message}`);
+
+    this.appErrorType = appErrorType;
+    this.message = message;
+    this.parentError = parentError;
+  }
+
+  isMe(error: unknown): error is this {
+    return AppError.isAppError(error, this.appErrorType);
+  }
+}

package/src/errors/errors.ts

@@ -0,0 +1,22 @@
+/**
+ * Error utilities shared across packages. Coercion of `unknown` values caught
+ * in `catch` blocks lives here, not at call sites.
+ */
+export class Errors {
+  static toError(value: unknown): Error {
+    if (value instanceof Error) {
+      return value;
+    }
+
+    if (typeof value === 'string') {
+      return new Error(value);
+    }
+
+    try {
+      return new Error(JSON.stringify(value) ?? String(value));
+    } catch {
+      // circular structures and exotic values still deserve an Error, not a crash
+      return new Error(String(value));
+    }
+  }
+}

package/src/languages.ts

@@ -0,0 +1,133 @@
+// LANGUAGE ADDRESSING — how a page's address names its language. The platform owns it: the router
+// reads the language off an address, the server writes canonical addresses and the sitemap, and
+// blocks never learn it — they ask for "this path" or "this page in German" (`useHref` in
+// @mosetta/react), and `resolveHref` below puts the language where the scheme says. One scheme
+// today — the language as the path's first segment, none for the project's default
+// (`/ru/blog/x`) — behind a port, so another (a suffix, a subdomain) is a new scheme, not a change
+// of every block.
+
+export interface ILanguageSet {
+  /** ISO 639-1 codes, the default first */
+  readonly languages: readonly string[];
+  readonly defaultLanguage: string;
+}
+
+export interface ILanguageOfAddress {
+  readonly lang: string;
+  /** the address's path with the language taken out — what the route table is matched against */
+  readonly path: string;
+  /** the address named the language itself (the default may be named too) */
+  readonly named: boolean;
+}
+
+/** the port: an address → its language and path; a path and a language → the address */
+export interface ILanguageScheme {
+  read(pathname: string, languages: ILanguageSet): ILanguageOfAddress;
+  write(path: string, lang: string, languages: ILanguageSet): string;
+}
+
+export type TLanguageSchemeName = 'prefix';
+
+const PREFIX_RE = /^\/([A-Za-z]{2}(?:-[A-Za-z]{2})?)(?=\/|$)/;
+
+/** `/ru/blog/x` ↔ ru + `/blog/x`; the default language has no prefix */
+const prefixScheme: ILanguageScheme = {
+  read(pathname, languages) {
+    const code = PREFIX_RE.exec(pathname)?.[1].toLowerCase();
+    if (code && languages.languages.includes(code)) {
+      return { lang: code, path: pathname.slice(code.length + 1) || '/', named: true };
+    }
+    return { lang: languages.defaultLanguage, path: pathname, named: false };
+  },
+  write(path, lang, languages) {
+    if (lang === languages.defaultLanguage || !languages.languages.includes(lang)) return path;
+    return path === '/' ? `/${lang}` : `/${lang}${path}`;
+  },
+};
+
+const SCHEMES: Readonly<Record<TLanguageSchemeName, ILanguageScheme>> = { prefix: prefixScheme };
+
+/** the named scheme; anything unknown is the default one */
+export const languageScheme = (name?: string): ILanguageScheme => SCHEMES[name as TLanguageSchemeName] ?? prefixScheme;
+
+/** a path in a language, the default scheme — what the server writes canonical addresses with */
+export const pathInLanguage = (path: string, lang: string, languages: ILanguageSet): string => prefixScheme.write(path, lang, languages);
+
+/** languages written right to left — a page in one of them is laid out mirrored */
+const RTL = new Set(['ar', 'he', 'fa', 'ur']);
+export const isRightToLeft = (lang: string | undefined): boolean => RTL.has((lang ?? '').split('-')[0].toLowerCase());
+
+// ---- addresses for blocks ----
+
+/** what the server stamps for the routing hooks: the scheme and the project's languages */
+export interface IAddressing extends ILanguageSet {
+  readonly scheme: TLanguageSchemeName;
+}
+
+/** where the reader is, as the hooks see it */
+export interface IHrefContext {
+  /** the current page's path without its language */
+  readonly path: string;
+  readonly search: Readonly<Record<string, string>>;
+  readonly lang?: string;
+  readonly addressing?: IAddressing;
+}
+
+export interface IHrefOptions {
+  /** the address in this language instead of the reader's (a language switcher) */
+  readonly lang?: string;
+  /**
+   * the query: for the current page it is MERGED into the current one (null removes a key); for
+   * another path it is the whole query
+   */
+  readonly query?: Readonly<Record<string, string | null>>;
+}
+
+const EXTERNAL_RE = /^([a-z][a-z0-9+.-]*:|\/\/)/i;
+
+/** a target's path, query and fragment, a relative path resolved against the current page */
+function partsOf(target: string, currentPath: string): { path: string; search: string; hash: string } {
+  const url = new URL(target, `http://site${currentPath}`);
+  return { path: url.pathname, search: url.search, hash: url.hash };
+}
+
+const queryString = (entries: Iterable<[string, string]>): string => {
+  const params = new URLSearchParams([...entries]);
+  const s = params.toString();
+  return s ? `?${s}` : '';
+};
+
+/**
+ * The address a block links to: `target` is a path of this site as its author wrote it (`/blog`,
+ * `blog/x` relative to the page, `?page=2`), or nothing for the current page; the language goes
+ * where the scheme puts it — the reader's, or the one asked for. An address of another site, a
+ * `mailto:`, a bare `#fragment` is returned as it is: no language of ours belongs there.
+ */
+export function resolveHref(context: IHrefContext, target?: string, options: IHrefOptions = {}): string {
+  if (target !== undefined && (EXTERNAL_RE.test(target) || target.startsWith('#'))) return target;
+  const addressing = context.addressing;
+  const lang = options.lang ?? context.lang ?? addressing?.defaultLanguage ?? '';
+  const write = (path: string): string => (addressing ? languageScheme(addressing.scheme).write(path, lang, addressing) : path);
+  if (target === undefined || target === '') {
+    const merged = new Map(Object.entries(context.search));
+    for (const [key, value] of Object.entries(options.query ?? {})) {
+      if (value === null) merged.delete(key);
+      else merged.set(key, value);
+    }
+    return `${write(context.path || '/')}${queryString(merged)}`;
+  }
+  const parts = partsOf(target, context.path || '/');
+  const own = options.query
+    ? queryString(Object.entries(options.query).filter((e): e is [string, string] => e[1] !== null))
+    : parts.search;
+  return `${write(parts.path)}${own}${parts.hash}`;
+}
+
+/** whether a path (as its author wrote it) is where the reader is — exactly, or anywhere under it */
+export function isCurrentPath(context: IHrefContext, target: string, under = false): boolean {
+  if (EXTERNAL_RE.test(target) || target.startsWith('#')) return false;
+  const own = partsOf(target, context.path || '/').path;
+  const here = context.path || '/';
+  if (here === own) return true;
+  return under && here.startsWith(own.endsWith('/') ? own : `${own}/`);
+}

package/src/models/commonModels.ts

@@ -0,0 +1,42 @@
+export interface IWithVersion {
+  readonly version: string;
+}
+
+export interface IWithId {
+  readonly id: string;
+}
+
+export interface IWithTileName {
+  readonly name: string;
+}
+
+export interface IWithNamespace {
+  readonly namespace: string;
+}
+export interface IWithType {
+  readonly type: string;
+}
+
+export interface ITileReference extends IWithTileName, IWithVersion, IWithNamespace, IWithType {
+}
+
+export interface IWithTileReference {
+  readonly reference: ITileReference;
+}
+
+export interface IBlueprintNode extends IWithId {
+  readonly reference: string;
+  readonly children: IBlueprintNode[];
+  readonly slot?: string;
+  /**
+   * Node settings: seeded from defaultSettings() at
+   * insertion in the editor, complete-and-valid by the time they reach prod — the runtime never
+   * merges or validates. On a PAGE root the `versions` key is reserved for version resolution config.
+   */
+  readonly settings?: Record<string, unknown>;
+}
+
+export interface IWithBlueprintNode {
+  readonly moduleTreeNode: IBlueprintNode;
+}
+

package/src/models/pageModels.ts

@@ -0,0 +1,38 @@
+import type { IAddressing } from '../languages';
+import { IBlueprintNode } from './commonModels';
+
+/**
+ * What the request URL said to the page's route pattern: named segments (`{slug}`), a rest
+ * segment (`{...path}`, an array) and captured query values (`?q={query}`). Stamped into the
+ * envelope by the server render; a page reads it with `useRoute()`.
+ */
+export interface IRouteMatch {
+  readonly pattern: string;
+  readonly params: Readonly<Record<string, string | string[]>>;
+  readonly query: Readonly<Record<string, string>>;
+  /** the language the address names (ISO 639-1); the project's default when the URL names none */
+  readonly lang?: string;
+  /** how addresses name the language, and the project's languages — read by the routing hooks
+   *  (`useHref`, `useLanguages`); a block has no business with it */
+  readonly addressing?: IAddressing;
+  /** the request's path without its language (`/blog/x` for `/ru/blog/x`) */
+  readonly path?: string;
+  /** every value of the request's query string (`query` holds only those the pattern captures) */
+  readonly search?: Readonly<Record<string, string>>;
+}
+
+export interface IBlueprint extends IBlueprintNode {
+  readonly pattern: string;
+  /** the route match of the current request (server-stamped; absent in a bare static build) */
+  readonly route?: IRouteMatch;
+  /**
+   * Module rendered in place of a branch that failed. Optional because a page document may simply
+   * not name one — every reader already guards, and the boot envelope has always been typed that
+   * way (the manager used to take it through a cast).
+   */
+  readonly fallback?: string;
+}
+
+export interface IWithPage {
+  readonly page: IBlueprint;
+}

package/src/models/tileHosts.ts

@@ -0,0 +1,112 @@
+// A SITE'S TILE HOSTS, merged (ADR-0070): the tile host descriptors (`modules.json`) of every tile
+// host the site's tiles come from — the platform's (the primary, first), a project's tile palettes,
+// another vendor's — as ONE factory tile descriptor, where a tile's address is its host's base and
+// the formula (`modules/<id>/<id>.js`), found by its id. A blueprint never says where its tiles lie:
+// the descriptor does.
+//
+// Conflicts are decided here, by the factory, never in the browser:
+// - a tile BRAND belongs to one tile host — the first that has anything of it: tiles of `acme` are
+//   read only from the host that holds `acme`, and a second host's tiles of it are left out (said,
+//   in the warnings);
+// - PACKAGE tiles (`_ns_package_…`) may sit with several: one id is one set of bytes, and the first
+//   host that has it is the one read from (as the first released copy of a package stands); other
+//   bytes under the same id are said, the first still stands;
+// - a tile of a host other than the primary is taken only with its TILE INTEGRITY: the bytes the
+//   factory and the browser load from there are checked against it. A tile palette descriptor and a
+//   fragment name no artifact of their own and need none.
+/** what the merge reads of a tile descriptor — the factory's and the editor's carry more */
+export interface ITileDescriptorLike {
+  readonly id: string;
+  readonly reference?: { readonly type?: string };
+  readonly integrity?: string;
+  /** the tile host it is read from; absent — the primary */
+  readonly provider?: string;
+}
+
+const NAMESPACE_RE = /^_ns_([a-z0-9-]+)_t_/;
+
+/** the namespace whose entities any source may hold: one id is one set of bytes */
+const SHARED_NAMESPACE = 'package';
+
+/** the sides that name no artifact of their own — a tile palette descriptor, a fragment */
+const WITHOUT_ARTIFACT = new Set(['distribution', 'prefab']);
+
+/** whether a tile vouches for the bytes of its artifact — what a host other than the primary must do */
+const vouched = (entity: ITileDescriptorLike): boolean => WITHOUT_ARTIFACT.has(entity.reference?.type ?? '')
+  || (typeof entity.integrity === 'string' && /^sha(256|384|512)-/.test(entity.integrity));
+
+/** the namespace an id names, or null for an id of no namespace */
+export const brandOfId = (id: string): string | null => NAMESPACE_RE.exec(id)?.[1] ?? null;
+
+/** one source's catalogs as read: its key, its public and its private entities */
+export interface ITileHostDescriptors<T extends ITileDescriptorLike = ITileDescriptorLike> {
+  readonly key: string;
+  readonly public: readonly T[];
+  readonly private: readonly T[];
+}
+
+export interface IMergedDescriptors<T extends ITileDescriptorLike = ITileDescriptorLike> {
+  /** every entity once — one of a source other than the host carries that source's key (`provider`) */
+  readonly entities: readonly T[];
+  /** id → the key of the source it is read from */
+  readonly tileHostOf: ReadonlyMap<string, string>;
+}
+
+export interface IMergedTileHosts<T extends ITileDescriptorLike = ITileDescriptorLike> {
+  readonly public: IMergedDescriptors<T>;
+  readonly private: IMergedDescriptors<T>;
+  /** what was left out, and why */
+  readonly warnings: readonly string[];
+}
+
+/** the first source in order that has anything of a namespace owns it — over both sides of every source */
+function ownersOf(parts: readonly ITileHostDescriptors<ITileDescriptorLike>[]): Map<string, string> {
+  const owners = new Map<string, string>();
+  for (const part of parts) {
+    for (const entity of [...part.public, ...part.private]) {
+      const ns = typeof entity?.id === 'string' ? brandOfId(entity.id) : null;
+      if (ns && ns !== SHARED_NAMESPACE && !owners.has(ns)) owners.set(ns, part.key);
+    }
+  }
+  return owners;
+}
+
+export function mergeTileHosts<T extends ITileDescriptorLike>(parts: readonly ITileHostDescriptors<T>[]): IMergedTileHosts<T> {
+  const host = parts[0]?.key;
+  const owners = ownersOf(parts);
+  const warnings: string[] = [];
+  const said = new Set<string>();
+  const say = (line: string): void => {
+    if (said.has(line)) return;
+    said.add(line);
+    warnings.push(line);
+  };
+  const side = (pick: (part: ITileHostDescriptors<T>) => readonly T[]): IMergedDescriptors<T> => {
+    const taken = new Map<string, T>();
+    const tileHostOf = new Map<string, string>();
+    for (const part of parts) {
+      for (const entity of pick(part)) {
+        if (!entity || typeof entity.id !== 'string') continue;
+        const ns = brandOfId(entity.id);
+        const owner = ns && ns !== SHARED_NAMESPACE ? owners.get(ns) : undefined;
+        if (owner && owner !== part.key) {
+          say(`${part.key}: ${ns} belongs to ${owner} — its entities of ${ns} are not taken`);
+          continue;
+        }
+        if (part.key !== host && !vouched(entity)) {
+          say(`${part.key}: ${entity.id} names no integrity — not taken`);
+          continue;
+        }
+        const held = taken.get(entity.id);
+        if (held) {
+          if (held.integrity !== entity.integrity) say(`${entity.id}: ${part.key} has other bytes than ${tileHostOf.get(entity.id)} — the first stands`);
+          continue;
+        }
+        taken.set(entity.id, part.key === host ? entity : { ...entity, provider: part.key });
+        tileHostOf.set(entity.id, part.key);
+      }
+    }
+    return { entities: [...taken.values()], tileHostOf };
+  };
+  return { public: side((p) => p.public), private: side((p) => p.private), warnings };
+}

package/src/routing.ts

@@ -0,0 +1,143 @@
+import type { IRouteMatch } from './models/pageModels';
+
+// What the BROWSER and the server share about addresses: the pattern matcher (a page's route
+// against a URL — the server picks the page, a client router re-reads the route of the page it
+// already shows on a shallow move) and the marker that asks a page's address for its DOCUMENT
+// instead of its HTML. Pure functions, no DOM, no node.
+
+/**
+ * The query parameter that turns a page's address into a request for its DOCUMENT: the same
+ * envelope the HTML carries in `#pageContent`, as JSON, for a client-side move. In the ADDRESS,
+ * not in a header: the edge caches key by the whole URL and look at no header, so the two forms
+ * of one address must differ there. The server leaves it out of `route.search`.
+ */
+export const DOCUMENT_QUERY_PARAM = '__mosetta_doc';
+
+// Route PATTERNS. A page's pattern is a path with parameters, optionally followed by query
+// requirements:
+//
+//   /blog/{slug}                      one segment, captured
+//   /{lang}/blog/{slug}               two captures
+//   /files/{...path}                  a REST: zero or more segments, captured as an array
+//   /{lang}/{...path}/edit            a rest in the middle: the segments before it match from the
+//                                     left, the ones after it from the right, it takes what is between
+//   /search?q={query}                 a query value captured when present
+//   /promo/{id}?kind=static&ref={r}   a query literal REQUIRED to match, a capture beside it
+//
+// Matching never reads page documents: the pattern lives in the published listing's key. When
+// several routes match, the most SPECIFIC one wins — compared segment by segment (a literal
+// beats a capture, a capture beats a rest), then by the number of query requirements, then by
+// the pattern text, so the choice is deterministic whatever the store's order. No match is no
+// page: an honest 404, never "the first route".
+
+type TSegment
+  = | { readonly kind: 'literal'; readonly text: string }
+  | { readonly kind: 'param'; readonly name: string }
+  | { readonly kind: 'rest'; readonly name: string };
+
+type TQueryRule
+  = | { readonly key: string; readonly kind: 'literal'; readonly value: string }
+  | { readonly key: string; readonly kind: 'param'; readonly name: string };
+
+export interface IParsedPattern {
+  readonly pattern: string;
+  readonly segments: readonly TSegment[];
+  readonly query: readonly TQueryRule[];
+}
+
+const PARAM_RE = /^\{([A-Za-z_][A-Za-z0-9_]*)\}$/;
+const REST_RE = /^\{\.\.\.([A-Za-z_][A-Za-z0-9_]*)\}$/;
+
+const safeDecode = (s: string): string => {
+  try {
+    return decodeURIComponent(s);
+  } catch {
+    return s;
+  }
+};
+
+/** path → decoded segments, the root and a trailing slash both meaning "no segment there" */
+export const splitPath = (pathname: string): string[] => pathname.split('/').filter(Boolean).map(safeDecode);
+
+export function parsePattern(pattern: string): IParsedPattern {
+  const at = pattern.indexOf('?');
+  const path = at === -1 ? pattern : pattern.slice(0, at);
+  const search = at === -1 ? '' : pattern.slice(at + 1);
+  const names = new Set<string>();
+  const claim = (name: string): string => {
+    if (names.has(name)) throw new Error(`route pattern "${pattern}": {${name}} is captured twice`);
+    names.add(name);
+    return name;
+  };
+  const segments: TSegment[] = splitPath(path).map((raw) => {
+    const rest = REST_RE.exec(raw);
+    if (rest) return { kind: 'rest', name: claim(rest[1]) };
+    const param = PARAM_RE.exec(raw);
+    return param ? { kind: 'param', name: claim(param[1]) } : { kind: 'literal', text: raw };
+  });
+  // one rest at most: with two, the split between them would be a guess
+  if (segments.filter((s) => s.kind === 'rest').length > 1) throw new Error(`route pattern "${pattern}": only one {...rest} segment`);
+  const query: TQueryRule[] = [];
+  new URLSearchParams(search).forEach((value, key) => {
+    const param = PARAM_RE.exec(value);
+    query.push(param ? { key, kind: 'param', name: claim(param[1]) } : { key, kind: 'literal', value });
+  });
+  return { pattern, segments, query };
+}
+
+/** the match of one pattern against a request URL, or null */
+export function matchPattern(parsed: IParsedPattern, url: URL): IRouteMatch | null {
+  const path = splitPath(url.pathname);
+  const params: Record<string, string | string[]> = {};
+  const { segments } = parsed;
+  const restAt = segments.findIndex((s) => s.kind === 'rest');
+  const one = (seg: TSegment, value: string): boolean => {
+    if (seg.kind === 'literal') return seg.text === value;
+    if (seg.kind === 'param') params[seg.name] = value;
+    return true;
+  };
+  if (restAt === -1) {
+    if (path.length !== segments.length) return null;
+    for (let i = 0; i < segments.length; i++) if (!one(segments[i], path[i])) return null;
+  } else {
+    // the prefix matches from the left, the suffix from the right, the rest takes the middle
+    const before = segments.slice(0, restAt);
+    const after = segments.slice(restAt + 1);
+    if (path.length < before.length + after.length) return null;
+    for (let i = 0; i < before.length; i++) if (!one(before[i], path[i])) return null;
+    for (let i = 0; i < after.length; i++) if (!one(after[i], path[path.length - after.length + i])) return null;
+    const rest = segments[restAt] as { kind: 'rest'; name: string };
+    params[rest.name] = path.slice(before.length, path.length - after.length);
+  }
+  const query: Record<string, string> = {};
+  for (const rule of parsed.query) {
+    const value = url.searchParams.get(rule.key);
+    if (rule.kind === 'literal') {
+      if (value !== rule.value) return null;
+    } else if (value !== null) {
+      query[rule.name] = value;
+    }
+  }
+  return { pattern: parsed.pattern, params, query };
+}
+
+// a literal beats a capture, a capture beats a rest — and a pattern that ENDS where the other
+// still swallows a rest is the more exact of the two (`/` over `/{...all}`)
+const KIND_RANK: Record<TSegment['kind'], number> = { literal: 3, param: 2, rest: 1 };
+const ENDED_RANK = 1.5;
+
+/** negative when `a` is the more specific pattern */
+export function compareSpecificity(a: IParsedPattern, b: IParsedPattern): number {
+  const n = Math.max(a.segments.length, b.segments.length);
+  for (let i = 0; i < n; i++) {
+    const ra = a.segments[i] ? KIND_RANK[a.segments[i].kind] : ENDED_RANK;
+    const rb = b.segments[i] ? KIND_RANK[b.segments[i].kind] : ENDED_RANK;
+    if (ra !== rb) return rb - ra;
+  }
+  const qa = a.query.filter((q) => q.kind === 'literal').length;
+  const qb = b.query.filter((q) => q.kind === 'literal').length;
+  if (qa !== qb) return qb - qa;
+  if (a.query.length !== b.query.length) return b.query.length - a.query.length;
+  return a.pattern.localeCompare(b.pattern);
+}
+

package/src/styler.ts

@@ -0,0 +1,152 @@
+// THE STYLER: what a block lets its users restyle from outside, without touching its code. A
+// block names its PARTS — the elements worth styling (`root`, `label`, `cover`…); a node keeps its
+// overrides in `settings.styles`: part → state → a set of allowed CSS properties. The block's
+// runtime marks each part with one attribute (`useStyler` in @mosetta/react), and the rules below
+// are generated per node — so a hover state and a narrow screen work, and the server render
+// ships them in the head. This module is pure data: the vocabulary, the cleaning, the CSS.
+
+/** the settings key a node keeps its styles under */
+export const STYLES_SETTING = 'styles';
+
+/** the attribute a part carries: `<node id>.<part>` — unique on the page, whatever nests inside */
+export const STYLE_ATTRIBUTE = 'data-mosetta-style';
+
+/** where a declaration applies: always, under the pointer, on a narrow screen, or on the link to
+ *  where the reader is (`aria-current`: the current category, the current language, this page) */
+export type TStyleState = 'base' | 'hover' | 'mobile' | 'current';
+export const STYLE_STATES: readonly TStyleState[] = ['base', 'hover', 'current', 'mobile'];
+
+/** the width at and below which `mobile` applies */
+export const MOBILE_MAX_WIDTH = 640;
+
+export type TStyleGroup = 'text' | 'box' | 'border' | 'layout' | 'effects';
+
+export interface IStyleProperty {
+  /** the camelCase name the settings store */
+  readonly name: string;
+  readonly label: string;
+  readonly group: TStyleGroup;
+  /** how the form edits it: free text, a colour, or one of a few values */
+  readonly input: 'text' | 'color' | 'choice';
+  readonly choices?: readonly string[];
+  readonly placeholder?: string;
+}
+
+/** the properties a user may set — deliberately not all of CSS: what shapes a block's look */
+export const STYLE_PROPERTIES: readonly IStyleProperty[] = [
+  { name: 'fontFamily', label: 'Font', group: 'text', input: 'text', placeholder: 'var(--theme-font-body)' },
+  { name: 'fontSize', label: 'Size', group: 'text', input: 'text', placeholder: '16px' },
+  { name: 'fontWeight', label: 'Weight', group: 'text', input: 'choice', choices: ['300', '400', '500', '600', '700', '800'] },
+  { name: 'fontStyle', label: 'Slant', group: 'text', input: 'choice', choices: ['normal', 'italic'] },
+  { name: 'lineHeight', label: 'Line height', group: 'text', input: 'text', placeholder: '1.5' },
+  { name: 'letterSpacing', label: 'Letter spacing', group: 'text', input: 'text', placeholder: '-0.02em' },
+  { name: 'color', label: 'Colour', group: 'text', input: 'color' },
+  { name: 'textAlign', label: 'Align', group: 'text', input: 'choice', choices: ['left', 'center', 'right'] },
+  { name: 'textTransform', label: 'Case', group: 'text', input: 'choice', choices: ['none', 'uppercase', 'lowercase', 'capitalize'] },
+  { name: 'textDecoration', label: 'Decoration', group: 'text', input: 'choice', choices: ['none', 'underline'] },
+  { name: 'background', label: 'Background', group: 'box', input: 'color' },
+  { name: 'padding', label: 'Padding', group: 'box', input: 'text', placeholder: '16px 24px' },
+  { name: 'margin', label: 'Margin', group: 'box', input: 'text', placeholder: '0 auto' },
+  { name: 'width', label: 'Width', group: 'box', input: 'text', placeholder: '100%' },
+  { name: 'maxWidth', label: 'Max width', group: 'box', input: 'text', placeholder: '1200px' },
+  { name: 'height', label: 'Height', group: 'box', input: 'text', placeholder: 'auto' },
+  { name: 'minHeight', label: 'Min height', group: 'box', input: 'text', placeholder: '400px' },
+  { name: 'aspectRatio', label: 'Aspect ratio', group: 'box', input: 'text', placeholder: '16 / 9' },
+  { name: 'objectFit', label: 'Fit', group: 'box', input: 'choice', choices: ['cover', 'contain', 'fill'] },
+  { name: 'border', label: 'Border', group: 'border', input: 'text', placeholder: '1px solid #e4e4e7' },
+  { name: 'borderRadius', label: 'Radius', group: 'border', input: 'text', placeholder: '12px' },
+  { name: 'boxShadow', label: 'Shadow', group: 'border', input: 'text', placeholder: '0 8px 24px rgb(0 0 0 / 8%)' },
+  { name: 'display', label: 'Display', group: 'layout', input: 'choice', choices: ['block', 'flex', 'grid', 'inline-flex', 'none'] },
+  { name: 'flexDirection', label: 'Direction', group: 'layout', input: 'choice', choices: ['row', 'column'] },
+  { name: 'flexWrap', label: 'Wrap', group: 'layout', input: 'choice', choices: ['nowrap', 'wrap'] },
+  { name: 'gap', label: 'Gap', group: 'layout', input: 'text', placeholder: '16px' },
+  { name: 'justifyContent', label: 'Justify', group: 'layout', input: 'choice', choices: ['flex-start', 'center', 'flex-end', 'space-between'] },
+  { name: 'alignItems', label: 'Align items', group: 'layout', input: 'choice', choices: ['stretch', 'flex-start', 'center', 'flex-end'] },
+  { name: 'opacity', label: 'Opacity', group: 'effects', input: 'text', placeholder: '0.8' },
+  { name: 'filter', label: 'Filter', group: 'effects', input: 'text', placeholder: 'blur(24px)' },
+  { name: 'transition', label: 'Transition', group: 'effects', input: 'text', placeholder: 'all 150ms ease' },
+];
+
+const KNOWN = new Map(STYLE_PROPERTIES.map((p) => [p.name, p]));
+
+/** one state's declarations: property → value */
+export type TStyleDeclarations = Readonly<Record<string, string>>;
+/** one part's styles: state → declarations */
+export type TPartStyles = Readonly<Partial<Record<TStyleState, TStyleDeclarations>>>;
+/** a node's styles: part → its styles */
+export type TStyles = Readonly<Record<string, TPartStyles>>;
+
+/**
+ * A value as it may enter a stylesheet, or null: nothing that ends a declaration or a rule, opens
+ * an at-rule, a comment or markup; an image only from an https address.
+ */
+export function cleanStyleValue(value: unknown): string | null {
+  if (typeof value !== 'string') return null;
+  const v = value.trim();
+  if (!v || v.length > 300) return null;
+  if (/[;{}<>@\\]|\/\*/.test(v)) return null;
+  const urls = v.match(/url\(([^)]*)\)/gi) ?? [];
+  if (urls.some((u) => !/^url\(\s*["']?https:\/\//i.test(u))) return null;
+  return v;
+}
+
+/** the styles as they may be rendered: known parts shape, known states, known properties, clean values */
+export function cleanStyles(styles: unknown): TStyles {
+  if (!styles || typeof styles !== 'object' || Array.isArray(styles)) return {};
+  const out: Record<string, TPartStyles> = {};
+  for (const [part, states] of Object.entries(styles as Record<string, unknown>)) {
+    if (!/^[a-z][A-Za-z0-9]*$/.test(part) || !states || typeof states !== 'object') continue;
+    const partOut: Partial<Record<TStyleState, TStyleDeclarations>> = {};
+    for (const state of STYLE_STATES) {
+      const decls = (states as Record<string, unknown>)[state];
+      if (!decls || typeof decls !== 'object') continue;
+      const clean: Record<string, string> = {};
+      for (const [name, value] of Object.entries(decls as Record<string, unknown>)) {
+        const v = KNOWN.has(name) ? cleanStyleValue(value) : null;
+        if (v !== null) clean[name] = v;
+      }
+      if (Object.keys(clean).length) partOut[state] = clean;
+    }
+    if (Object.keys(partOut).length) out[part] = partOut;
+  }
+  return out;
+}
+
+/**
+ * A variable a style value may name — `var(--theme-accent)`: what the themes around a block
+ * declare, as the styler's form offers them. The value is the one in the theme the author sees.
+ */
+export interface IStyleVariable {
+  /** the custom property: `--theme-accent` */
+  readonly name: string;
+  readonly label: string;
+  readonly kind: 'color' | 'font' | 'value';
+  readonly value?: string;
+}
+
+/** the value of a part's attribute */
+export const stylePartKey = (nodeId: string, part: string): string => `${nodeId}.${part}`;
+
+const kebab = (name: string): string => name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+const cssString = (value: string): string => value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+const block = (decls: TStyleDeclarations): string => Object.entries(decls).map(([n, v]) => `${kebab(n)}:${v}`).join(';');
+
+/**
+ * The stylesheet of one node: a rule per part and state. The selector carries an id-level weight
+ * (`:not(#\#)` matches everything and counts as an id), so an override wins over the block's own
+ * class-scoped css without `!important` — the user's styling is the last word.
+ */
+export function stylerCss(nodeId: string, styles: unknown): string {
+  // the sheet travels as raw inner html of a <style>: an id that could close it renders nothing
+  if (/[<>]/.test(nodeId)) return '';
+  const clean = cleanStyles(styles);
+  const rules: string[] = [];
+  for (const [part, states] of Object.entries(clean)) {
+    const selector = `[${STYLE_ATTRIBUTE}="${cssString(stylePartKey(nodeId, part))}"]:not(#\\#)`;
+    if (states.base) rules.push(`${selector}{${block(states.base)}}`);
+    if (states.hover) rules.push(`${selector}:hover{${block(states.hover)}}`);
+    if (states.current) rules.push(`${selector}[aria-current]{${block(states.current)}}`);
+    if (states.mobile) rules.push(`@media (max-width:${MOBILE_MAX_WIDTH}px){${selector}{${block(states.mobile)}}}`);
+  }
+  return rules.join('\n');
+}

package/src/theme.ts

@@ -0,0 +1,224 @@
+// THEMING: a project's look as CSS variables, defined once and switched as a whole.
+//
+// A theme block wraps a part of the page (the whole page, from its root): it declares VARIABLES —
+// a key and a human name each (`primary` · "Primary") — and THEMES that give every variable a
+// value (light, dark, a festive one…). Its element carries the active theme's values as
+// `--theme-<key>` custom properties, which every block inside inherits. Blocks never learn which
+// theme is on: they read the variables, each with a fallback of its own, and look as they always
+// did where no theme is.
+//
+// The THEME ROLES below are the protocol: variables any block of any library may count on (the
+// ui kit's whole palette is built from them). A theme may declare more variables of its own —
+// for the styler, for a project's own blocks.
+//
+// Which theme is on: the one the reader picked (kept in their browser), else — when the theme
+// follows the system — the one matching the system's light or dark, else the default. All of it
+// is CSS, rendered on the server: the system's choice is a media query, the reader's an attribute
+// on the document root that a tiny script in the head sets before the body paints. No flash of
+// the wrong theme, no script needed for the system's.
+import { cleanStyleValue } from './styler';
+
+export type TThemeVariableKind = 'color' | 'font' | 'value';
+export type TColorScheme = 'light' | 'dark';
+
+export interface IThemeVariable {
+  /** what the CSS names it: `--theme-<key>` */
+  readonly key: string;
+  /** what the editor calls it */
+  readonly label: string;
+  readonly kind: TThemeVariableKind;
+  /** a font: fetched from Google Fonts by its family */
+  readonly google?: boolean;
+}
+
+export interface IThemeVariant {
+  readonly id: string;
+  readonly label: string;
+  /** what the browser's own controls (scrollbars, inputs) should look like under it */
+  readonly scheme: TColorScheme;
+  /** variable key → value; a font's value is its family */
+  readonly values: Readonly<Record<string, string>>;
+}
+
+export interface IThemeSettings {
+  readonly variables: readonly IThemeVariable[];
+  readonly themes: readonly IThemeVariant[];
+  /** the theme on when nothing else decides */
+  readonly defaultTheme: string;
+  /** the system's light or dark picks the theme of that scheme, unless the reader picked one */
+  readonly followSystem: boolean;
+  /** where the reader's pick is kept — one name per site, so every page shares it */
+  readonly storageKey: string;
+  /** the page's own background follows the theme too (a theme at the page's root) */
+  readonly paintPage?: boolean;
+}
+
+interface IThemeRole extends IThemeVariable {
+  readonly light: string;
+  readonly dark: string;
+}
+
+/** the variables every block may count on, with the values a new theme starts from */
+export const THEME_ROLES: readonly IThemeRole[] = [
+  { key: 'background', label: 'Background', kind: 'color', light: '#ffffff', dark: '#0f0f14' },
+  { key: 'text', label: 'Text', kind: 'color', light: '#09090b', dark: '#f4f4f5' },
+  { key: 'muted', label: 'Muted surface', kind: 'color', light: '#f4f4f5', dark: '#1d1d24' },
+  { key: 'muted-text', label: 'Secondary text', kind: 'color', light: '#71717a', dark: '#a1a1aa' },
+  { key: 'primary', label: 'Primary', kind: 'color', light: '#18181b', dark: '#fafafa' },
+  { key: 'primary-text', label: 'Text on primary', kind: 'color', light: '#fafafa', dark: '#18181b' },
+  { key: 'accent', label: 'Accent', kind: 'color', light: '#2f5bea', dark: '#7c9cff' },
+  { key: 'border', label: 'Borders', kind: 'color', light: '#e4e4e7', dark: '#2e2e38' },
+  { key: 'radius', label: 'Corner radius', kind: 'value', light: '0.5rem', dark: '0.5rem' },
+  { key: 'font-body', label: 'Body font', kind: 'font', google: true, light: 'Inter', dark: 'Inter' },
+  { key: 'font-heading', label: 'Heading font', kind: 'font', google: true, light: 'Inter', dark: 'Inter' },
+];
+
+/** the custom property a variable lands in */
+export const themeVariable = (key: string): string => `--theme-${key}`;
+
+/** where the reader's pick is kept in their browser */
+export const themeStorageName = (storageKey: string): string => `mosetta-theme:${storageKey}`;
+
+/** the document root's attribute naming the reader's pick (set before the body paints) */
+export const themeChoiceAttribute = (storageKey: string): string => `data-theme-${storageKey}`;
+
+/** the attribute a theme block's element carries: its node id */
+export const THEME_ATTRIBUTE = 'data-mosetta-theme';
+
+/** a fresh theme: every role, a light and a dark theme, following the system */
+export function defaultThemeSettings(): IThemeSettings {
+  const variables = THEME_ROLES.map(({ key, label, kind, google }) => ({ key, label, kind, ...(google ? { google } : {}) }));
+  const valuesOf = (scheme: TColorScheme) => Object.fromEntries(THEME_ROLES.map((r) => [r.key, r[scheme]]));
+  return {
+    variables,
+    themes: [
+      { id: 'light', label: 'Light', scheme: 'light', values: valuesOf('light') },
+      { id: 'dark', label: 'Dark', scheme: 'dark', values: valuesOf('dark') },
+    ],
+    defaultTheme: 'light',
+    followSystem: true,
+    storageKey: 'site',
+    paintPage: true,
+  };
+}
+
+const NAME = /^[a-z][a-z0-9-]{0,31}$/;
+const FAMILY = /^[A-Za-z0-9][A-Za-z0-9 ]{0,63}$/;
+
+/** the settings as they may be rendered: known shapes, safe names — whatever else is dropped */
+export function cleanThemeSettings(settings: unknown): IThemeSettings | null {
+  if (!settings || typeof settings !== 'object') return null;
+  const s = settings as Partial<IThemeSettings>;
+  const list = (value: unknown): Record<string, unknown>[] => (Array.isArray(value) ? value : [])
+    .filter((item): item is Record<string, unknown> => !!item && typeof item === 'object');
+  const variables = list(s.variables)
+    .filter((v) => typeof v.key === 'string' && NAME.test(v.key) && ['color', 'font', 'value'].includes(v.kind as string)) as unknown as IThemeVariable[];
+  const themes = list(s.themes)
+    .filter((t) => typeof t.id === 'string' && NAME.test(t.id) && !!t.values && typeof t.values === 'object') as unknown as IThemeVariant[];
+  if (!themes.length) return null;
+  const storageKey = typeof s.storageKey === 'string' && NAME.test(s.storageKey) ? s.storageKey : 'site';
+  const defaultTheme = themes.some((t) => t.id === s.defaultTheme) ? s.defaultTheme! : themes[0].id;
+  return {
+    variables,
+    themes: themes.map((t) => ({ ...t, label: typeof t.label === 'string' ? t.label : t.id, scheme: t.scheme === 'dark' ? 'dark' : 'light' })),
+    defaultTheme,
+    followSystem: s.followSystem === true,
+    storageKey,
+    paintPage: s.paintPage !== false,
+  };
+}
+
+/** a variable's value as CSS, or null: a font becomes a family with fallbacks, the rest is cleaned */
+function cssValue(variable: IThemeVariable, value: unknown): string | null {
+  if (variable.kind !== 'font') return cleanStyleValue(value);
+  if (typeof value !== 'string' || !FAMILY.test(value.trim())) return null;
+  return `"${value.trim()}",ui-sans-serif,system-ui,sans-serif`;
+}
+
+function declarations(settings: IThemeSettings, theme: IThemeVariant): string {
+  const decls = settings.variables.flatMap((v) => {
+    const value = cssValue(v, theme.values[v.key]);
+    return value === null ? [] : [`${themeVariable(v.key)}:${value}`];
+  });
+  // what inherits — text colour and font — inherits from the theme's element too (it renders no box
+  // of its own, `display: contents`, yet its children inherit from it): a block that styles nothing
+  // reads the theme as well
+  const declared = new Set(settings.variables.map((v) => v.key));
+  const inherited = [
+    ...(declared.has('text') ? [`color:var(${themeVariable('text')})`] : []),
+    ...(declared.has('font-body') ? [`font-family:var(${themeVariable('font-body')})`] : []),
+  ];
+  return [...decls, ...inherited, `color-scheme:${theme.scheme}`].join(';');
+}
+
+/** the theme of a scheme the system asks for, when the theme follows the system */
+export function systemTheme(settings: IThemeSettings, scheme: TColorScheme): IThemeVariant | null {
+  return settings.themes.find((t) => t.scheme === scheme) ?? null;
+}
+
+/** which theme is on: the reader's pick, else the system's (when followed), else the default */
+export function activeThemeId(settings: IThemeSettings, chosen: string | null, systemScheme: TColorScheme | null): string {
+  if (chosen && settings.themes.some((t) => t.id === chosen)) return chosen;
+  if (settings.followSystem && systemScheme) {
+    const fromSystem = systemTheme(settings, systemScheme);
+    if (fromSystem) return fromSystem.id;
+  }
+  return settings.defaultTheme;
+}
+
+/**
+ * The stylesheet of one theme block: every theme's variables on its element — the default, the
+ * reader's pick by the root attribute, the system's by a media query — and, when it paints the
+ * page, the same choice for the page's own background.
+ */
+export function themeCss(nodeId: string, raw: unknown): string {
+  // the sheet travels as raw inner html of a <style>: an id that could close it renders nothing
+  if (/[<>"\\]/.test(nodeId)) return '';
+  const settings = cleanThemeSettings(raw);
+  if (!settings) return '';
+  const host = `[${THEME_ATTRIBUTE}="${nodeId}"]`;
+  const attr = themeChoiceAttribute(settings.storageKey);
+  const byId = new Map(settings.themes.map((t) => [t.id, t]));
+  const fallback = byId.get(settings.defaultTheme)!;
+  const backgroundOf = (theme: IThemeVariant): string => {
+    const bg = cleanStyleValue(theme.values.background);
+    return `${bg ? `background-color:${bg};` : ''}color-scheme:${theme.scheme}`;
+  };
+  const rules: string[] = [];
+  const both = (selectorHost: string, selectorPage: string, theme: IThemeVariant) => {
+    rules.push(`${selectorHost}{${declarations(settings, theme)}}`);
+    if (settings.paintPage) rules.push(`${selectorPage}{${backgroundOf(theme)}}`);
+  };
+  both(host, ':root', fallback);
+  if (settings.followSystem) {
+    for (const scheme of ['light', 'dark'] as const) {
+      const theme = systemTheme(settings, scheme);
+      if (!theme || theme === fallback) continue;
+      const hostRule = `:root:not([${attr}]) ${host}{${declarations(settings, theme)}}`;
+      const pageRule = settings.paintPage ? `:root:not([${attr}]){${backgroundOf(theme)}}` : '';
+      rules.push(`@media (prefers-color-scheme:${scheme}){${hostRule}${pageRule}}`);
+    }
+  }
+  // the reader's pick wins over the system's: these come last and weigh as much
+  for (const theme of settings.themes) both(`:root[${attr}="${theme.id}"] ${host}`, `:root[${attr}="${theme.id}"]`, theme);
+  return rules.join('\n');
+}
+
+/** the one Google Fonts stylesheet the themes' fonts need, or null when they name none */
+export function themeFontsHref(raw: unknown): string | null {
+  const settings = cleanThemeSettings(raw);
+  if (!settings) return null;
+  const googleKeys = settings.variables.filter((v) => v.kind === 'font' && v.google).map((v) => v.key);
+  const families = [...new Set(settings.themes.flatMap((t) => googleKeys.map((k) => t.values[k]))
+    .filter((f): f is string => typeof f === 'string' && FAMILY.test(f.trim()))
+    .map((f) => f.trim()))];
+  if (!families.length) return null;
+  return `https://fonts.googleapis.com/css2?${families.map((f) => `family=${f.replace(/ /g, '+')}:wght@400;500;600;700`).join('&')}&display=swap`;
+}
+
+/** the head script that puts the reader's kept pick on the document root before the body paints */
+export function themeChoiceScript(storageKey: string): string {
+  if (!NAME.test(storageKey)) return '';
+  return `try{var t=localStorage.getItem(${JSON.stringify(themeStorageName(storageKey))});`
+    + `if(t&&/^[a-z][a-z0-9-]{0,31}$/.test(t))document.documentElement.setAttribute(${JSON.stringify(themeChoiceAttribute(storageKey))},t)}catch(e){}`;
+}

package/tsconfig.base.json

@@ -0,0 +1,30 @@
+{
+  "compilerOptions": {
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "sourceMap": true,
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "downlevelIteration": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "target": "ESNext",
+    "outDir": "${configDir}/../../dist",
+    "rootDir": "${configDir}"
+  },
+  "include": [
+    "${configDir}/**/*.ts",
+    "${configDir}/**/*.tsx"
+  ],
+  "exclude": [
+    "${configDir}/node_modules"
+  ]
+}

package/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "./tsconfig.base.json",
+}