@small-web/kitten-types 1.0.0 → 1.0.1

package/global.d.ts

@@ -1,12 +1,8 @@
-// @small-web/kitten-types — ambient declaration of the global `kitten` namespace.
-//
-// This file declares the shape of `globalThis.kitten` so that consumers can use
-// the `kitten` global directly with full type safety, without importing a
-// runtime shim purely for types.
-//
-// The `KittenGlobal` interface is the single, hand-written source of truth for
-// the global namespace shape (previously reconstructed from runtime casts in
-// `@small-web/kitten`’s `globals.js`).
+/**
+  Kitten Types (@small-web/kitten-types)
+
+  Type declarations for global `kitten` namespace.
+*/
 
 import type { EventEmitter } from 'node:events'
 import type { Server } from 'node:https'
@@ -27,23 +23,32 @@ import type {
 
 import type { KittenIcons } from 'kitten-icons/types.d.ts'
 
-/** Tagged template function (e.g. `kitten.html`, `kitten.css`). */
+/**
+  Tagged template function (e.g. `kitten.html`, `kitten.css`).
+*/
 export type TaggedTemplate = (
   strings: TemplateStringsArray,
   ...properties: any[]
 ) => string | Array<string> | Promise<string | Array<string>>
 
-/** Sanitisation helper (e.g. `kitten.safelyAddHtml`, `kitten.sanitise`). */
+/**
+  Sanitisation helper (e.g. `kitten.safelyAddHtml`, `kitten.sanitise`).
+*/
 export type SanitisationFunction = (
   untrustedContent: string,
   allowedTags?: Array<string>,
   contact?: boolean
 ) => string
 
+/**
+  Record that maps URL fragments to hit counts.
+*/
 type StatsObject = Record<string, number>
 
-/** Internal Kitten database (`kitten._db`). */
-export interface KittenInternalDb {
+/**
+  Internal Kitten database (`kitten._db`).
+*/
+export interface KittenInternalDatabase {
   sessions: Record<string, Session>
   settings: {
     autoUpdate: {
@@ -77,7 +82,9 @@ export interface KittenInternalDb {
   uploads: Record<string, Upload>
 }
 
-/** The `kitten.uploads` store. */
+/**
+  The `kitten.uploads` store.
+*/
 export type UploadStore = {
   get(id: string): Upload
   length(): number
@@ -86,6 +93,9 @@ export type UploadStore = {
   delete(id: string): Promise<void>
 } & Record<string, Upload>
 
+/**
+  Configuration options for the Kitten server.
+*/
 interface ServerOptions {
   domain?: string
   port?: number
@@ -97,9 +107,12 @@ interface ServerOptions {
 }
 
 /**
-  The shape of the global `kitten` namespace.
+  Global `kitten` namespace.
 */
-export interface KittenGlobal {
+export interface kitten {
+  /**
+    Kitten’s version number and releated utilities.
+  */
   version: {
     date: Date
     versionStamp: number
@@ -114,30 +127,90 @@ export interface KittenGlobal {
     printToConsole: () => void
   }
 
+  /**
+    The Kitten app.
+
+    Includes references to the Kitten router (Polka) and server as well as the Kitten package (in deployed servers).
+  */
   app: {
+    /** The parsed package.json file for the current Kitten app (if any). */
     package?: any
     router: Polka
     server: Server
   }
 
-  // db is the custom database. If you want type safety for it, create a
-  // database app module in your project and declare the types there.
-  // See: https://codeberg.org/kitten/app#database-app-module
+  /**
+    This is your custom JSDB database.
+
+    If you want type safety for it, create a database app module in your project and declare the types there.
+
+    @see https://codeberg.org/kitten/app#database-app-module
+  */
   db: any
 
-  _db: KittenInternalDb
+  /**
+    Kitten’s internal database.
+
+    You should not need to access this directly.
+  */
+  _db: KittenInternalDatabase
 
+  /**
+    Represents an uploaded file.
+
+    @see https://kitten.small-web.org/tutorials/multipart-forms-and-file-uploads/
+  */
   Upload: typeof Upload
+
+  /**
+    Uploads sent to `POST` routes via `<input type='file'>` in your pages are automatically saved in your project’s uploads folder. Kitten also automatically assigns them unique IDs, maps to IDs to their locations on disk in its internal database (`kitten._db.uploads`), and serves them from the `/uploads/<unique-id>` route.
+
+    You can access uploads by ID from this global reference (which, itself, is simply a reference to `kitten._db.uploads`).
+
+    The Upload objects are also available to your `POST` routes in the `request.uploads` array.
+
+    @see https://kitten.small-web.org/tutorials/multipart-forms-and-file-uploads/
+  */
   uploads: UploadStore
+
+  /**
+    Kitten’s built-in icon set.
+
+    A subset of the Phosphor icon set by Helena Zhang and Tobias Fried as Kitten components.
+
+    @example
+    export default () => kitten.html`
+      <h1>I’m a cat! <${kitten.icons.Cat} /></h1>
+    `
+
+    @see
+    https://kitten.small-web.org/reference/#icons
+  */
   icons: KittenIcons
 
+  /**
+    The domain or Web Number (IP Address) Kitten is running at.
+  */
   domain: string
+
+  /**
+    The port number Kitten is running at.
+  */
   port: number
 
-  databaseDirectory: string
+  /**
+    The unique identifier for this Kitten site/app, calculated using the base path of the source code as well as the domain and port the server is running on.
+  */
   projectIdentifier: string
 
-  appRepository: {
+  /**
+    Represents the git repository of the app that Kitten is currently serving.
+
+    Available in production mode only (when Kitten is run with PRODUCTION=true).
+
+    @remarks For internal use only.
+  */
+  appRepository?: {
     upgradeAppToLatestCompatibleVersion(): Promise<void>
     upgradeAppToLatestAvailableCommit(): Promise<void>
     updateAppToVersion(versionTag: string): Promise<void>
@@ -154,7 +227,14 @@ export interface KittenGlobal {
     displayAppVersion(): void
   }
 
-  automaticUpdates: {
+  /**
+    Schedules and runs automatic updates of both Kitten itself and the app that Kitten is running.
+
+    Available in production mode only (when Kitten is run with PRODUCTION=true).
+
+    @remarks For internal use only.
+  */
+  automaticUpdates?: {
     interval: number
     intervalInHours: number
     timeToNextCheck(): number
@@ -164,9 +244,15 @@ export interface KittenGlobal {
     stop(): void
   }
 
-  // Note the mapping: `package` is exposed here even though the runtime shim
-  // exports it as `_package` (because `package` is a reserved word in strict
-  // mode for value bindings). As an interface property name it is valid.
+  /**
+    Represents the currently-installed Kitten package.
+
+    Provides information about and manages updates of the package by communicating with Kitten’s deployment site (https://kittens.small-web.org).
+
+    _Note that this class does NOT manage automatic updates. For that, please see the {@link AutomaticUpdates} class._
+
+    @remarks For internal use only.
+  */
   package: {
     hasCompatibleVersion: boolean
     isLatestReleaseVersion: boolean
@@ -176,36 +262,307 @@ export interface KittenGlobal {
     update(): Promise<void>
   }
 
+  /**
+    A truncated log of the last 25 request URLs for debugging purposes.
+  */
   requests: Array<string>
+
+  /**
+    Record of all active KittenPage instances, keyed by page ID (UUID).
+  */
   pages: Record<string, KittenPage>
+
+  /**
+    Global Kitten event emitter.
+  */
   events: EventEmitter
 
+  /**
+    KittenComponent class.
+
+    Extend this class to create your own stateful Kitten components.
+
+    @example
+    export default class MyComponent extends kitten.Component {
+      override html () {
+        return kitten.html`
+          What a lovely component I am! :)
+        `
+      }
+    }
+  */
   Component: typeof KittenComponent
+
+  /**
+    KittenPage class.
+
+    Extend this class to create your custom stateful Kitten pages.
+
+    @example
+    export default class MyPage extends kitten.Page {
+      override html () {
+        return kitten.html`
+          I am a KittenPage, short and sweet!
+        `
+      }
+    }
+  */
   Page: typeof KittenPage
 
+  /**
+    Kitten HTML tagged template string with support for Kitten components and JavaScript string interpolation.
+
+    This is the primary means of authoring HTML in Kitten.
+
+    @example
+    // A simple Kitten page (e.g., index.page.js) that says “Happy <month name>!” and uses the built-in kitten.icons.Smiley Kitten component to display a smiley.
+    export default function () {
+      const currentMonth = new Intl.DateTimeFormat('en-IE', { month: 'long' }).format(new Date())
+      return kitten.html`
+        <h1>Happy ${currentMonth}! <${kitten.icons.Smiley} /></h1>
+      `
+    }
+
+    @see https://kitten.small-web.org/reference/#html
+  */
   html: TaggedTemplate
+
+  /**
+    CSS tagged template.
+
+    Wraps passed string in `<style>…</style>` tags.
+
+    Useful if you want to use JavaScript variables in your CSS.
+
+    @example
+    const randomColour = ['red', 'green', 'blue'][Math.floor(Math.random()*3)]
+    const css = kitten.css`body { background-color: ${randomColour} }`
+
+    @see To include external static CSS, use CSS fragments (_.fragment.css_ files) instead. https://kitten.small-web.org/tutorials/components-and-fragments/#html-css-and-markdown-fragments
+  */
   css: TaggedTemplate
+
+  /**
+    JS tagged template. This is a basic function that simply attaches its input to the page
+    without any escaping. It can be used to get language intelligence/syntax highlighting
+    for Alpine.js snippets in your editor (if your editor and/or language server understands
+    to display kitten.js`` tagged templates as JavaScript).
+
+    Be careful if using this as you will have to escape backticks in your code and it
+    can make your code harder to read and understand for other people.
+
+    Use for simple things only.
+
+    @param {string[]} strings - Static strings.
+    @param {[]} interpolations - Interpolated values.
+  */
   js: TaggedTemplate
+
+  /**
+    Markdown wrapper.
+
+    Results in exactly the same thing as `` kitten.html`<markdown>…</markdown>` `` but without
+    requiring you to add the markdown tags. In a lot of ways more limited than just
+    using ``` kitten.html`` ``` with markdown tags inside it but might be nicer semantically in
+    certain cases.
+
+    @see https://kitten.small-web.org/reference/#markdown-support
+  */
   markdown: TaggedTemplate
+
+  /**
+    Reference to the MarkdownIt instance used internally by Kitten.
+
+    Use `kitten.md.render()` and `kitten.md.renderInline()` if you need more flexibility than what the other Markdown features in Kitten allow.
+
+    @example
+    <!-- Safely display comments on a blog that contain Markdown syntax. -->
+    <ul>
+      ${kitten.db.comments.map(comment => kitten.html`
+        <li>
+          <p>${kitten.safelyAddHtml(kitten.md.render(comment.message))}</p>
+          <p class='nameAndDate'>${comment.name} (${new Date(comment.date).toLocaleString()})</p>
+        </li>
+      `)}
+    </ul>
+  */
   md: MarkdownIt
 
+  /**
+    Slugify a string.
+
+    @example
+    kitten.slugify('I ♥ Dogs') // i-love-dogs
+
+    @see https://github.com/sindresorhus/slugify
+  */
   slugify: typeof Slugify
+
+  /**
+    YAML parser and serialiser.
+
+    Used internally by the Markdown loader for parsing YAML frontmatter but also exposed here for you to use in your own apps.
+
+    @example
+    kitten.yaml.parse(`
+      YAML:
+        - A human-readable data serialization language
+        - https://en.wikipedia.org/wiki/YAML
+    `)
+
+    @see https://github.com/eemeli/yaml
+  */
   yaml: typeof Yaml
 
+  /**
+    Kitten Crypto API
+
+    Crypographic functions used by Kitten and available for you to use in your own apps.
+
+    Remember that secrets that belong to people should only be handled on the client. The exact same API is available to use in the browser.
+
+    @example
+    // Client side use
+    <script type='module' async>
+      import { createKeys } from '/🐱/library/crypto-1.js'
+
+      async function generateSecret(event, secretView, copySecretButtonPlaceholder) {
+        const keys = await createKeys('${domain}')
+        const secret = keys.private.ed25519.asString
+      }
+    </script>
+  */
   crypto: {
+    /**
+      Converts Uint8Array to hex string.
+
+      From @noble/hashes.
+
+      @see https://github.com/paulmillr/noble-hashes#utils
+    */
     bytesToHex: (uint8a: Uint8Array) => string
+
+    /**
+      Decrypts passed encoded ciphertext using shared key.
+
+      From micro-aes-gcm.
+
+      @see https://www.npmjs.com/package/micro-aes-gcm
+    */
     decrypt: (sharedKey: Uint8Array, encoded: string | Uint8Array) => Uint8Array
+
+    /**
+      Convert emoji string to secret bytes.
+
+      @see https://kitten.small-web.org/reference/#cryptographic-properties
+    */
     emojiStringToSecret: (emojiString: string) => Uint8Array
+
+    /**
+      Encrypts passed plain text using the shared key.
+
+      From micro-aes-gcm.
+
+      @see https://www.npmjs.com/package/micro-aes-gcm
+    */
     encrypt: (sharedKey: Uint8Array, plaintext: string | Uint8Array) => Uint8Array
+
+    /**
+      Encrypts a message for a domain.
+
+      @param message Message to encrypt
+      @param ourPrivateKey Our emoji-encoded private key
+      @param domain The domain to encrypt the message for
+      @returns Hex-encoded encrypted message.
+
+      @remarks While this function can be used on the server, all encryption should be carried out on the client as the server should never have person’s secrets.
+    */
+    encryptMessageForDomain: (message: string, ourPrivateKey: string, domain: string) => Promise<string>
+
+    /**
+      Converts ed25519 private / public keys to Curve25519 and calculates Elliptic Curve Diffie Hellman (ECDH) with X25519. Conforms to RFC7748.
+
+      From `@noble/ed25519` (v1).
+
+      @see https://github.com/paulmillr/noble-ed25519/tree/v1#getsharedsecretprivatekey-publickey
+    */
     getSharedSecret: (
       privateKey: Uint8Array | string | bigint | number,
       publicKey: Uint8Array | string
     ) => Promise<Uint8Array>
+
+    /**
+      Converts hex string to Uint8Array .
+
+      From `@noble/hashes`.
+
+      @see https://github.com/paulmillr/noble-hashes#usage
+    */
     hexToBytes: (hex: string) => Uint8Array
+
+    /**
+      Produces cryptographically secure random Uint8Array of length bytes.
+
+      From `@noble/hashes`.
+
+      @see https://github.com/paulmillr/noble-hashes#utils
+    */
     randomBytes: (bytesLength?: number) => Uint8Array
+
+    /**
+      Generates cryptographically random 32-byte token and coverts it to hexadecimal representation.
+
+      Use anywhere you need a secret token (domain token, webhook secret, etc.)
+    */
     random32ByteTokenInHex: () => string
+
+    /**
+      Convert secret bytes to emoji string.
+
+      @see https://kitten.small-web.org/reference/#cryptographic-properties
+    */
     secretToEmojiString: (secret: Uint8Array) => string
+
+    /**
+      Calculates the shared secret for a domain using the domain’s public key and our private key.
+
+      Part of the Meow Protocol.
+    */
+    sharedSecretForDomain: (domain: string, ourPrivateKey: string) => Promise<Uint8Array>
+
+    /**
+      Signs message with privatek key and returns EdDSA signature.
+
+      From `@noble/ed25519` (v1).
+
+      @param message Message (not message hash) which would be signed
+      @param privateKey Private key which will sign the hash
+      @returns EdDSA signature. You can consume it with the `Signature.fromHex()` method: `Signature.fromHex(ed25519.sign(hash, privateKey))`
+
+      @see https://github.com/paulmillr/noble-ed25519/tree/v1#signmessage-privatekey
+    */
     sign: (message: Uint8Array | string, privateKey: Uint8Array | string) => Promise<Uint8Array>
+
+    /**
+      Verifies signature.
+
+      From `@noble/ed25519` (v1).
+
+      Compatible with [ZIP215](https://zips.z.cash/zip-0215), accepts:
+
+      ```
+      0 <= sig.R/publicKey < 2**256 (can be >= curve.P aka non-canonical encoding)
+      0 <= sig.s < l
+      ```
+
+      @param sig Signature returned by {@link sign} function
+      @param message Message to be verified
+      @param publicKey Public key (e.g., as generated from privateKey using it’s getPublicKey method)
+
+      @see https://github.com/paulmillr/noble-ed25519/tree/v1#verifysignature-message-publickey
+
+      @remarks Not compatible with RFC8032 because rfc encorces canonical encoding of R/publicKey. There is no security risk in ZIP behavior, and there is no effect on honestly generated signatures. For additional info about verification strictness, check out It’s [255:19AM](https://hdevalence.ca/blog/2020-10-04-its-25519am/).
+    */
     verify: (
       sig: Uint8Array | string | Signature,
       message: Uint8Array | string,
@@ -213,22 +570,123 @@ export interface KittenGlobal {
     ) => Promise<boolean>
   }
 
+  /**
+    Kitten utility functions and properties.
+  */
   utils: {
+    /**
+      Currently contains the same extensions as in {@link DYNAMIC_ROUTE_EXTENSIONS}.
+    */
     ALL_ROUTE_EXTENSIONS: Array<string>
+
+    /**
+      Extensions that Kitten treats as backend routes.
+
+      Currently: `socket.js` and `socket.ts`.
+
+      @see https://kitten.small-web.org/tutorials/htmx-the-htmx-web-socket-extension-and-socket-routes/
+    */
     BACKEND_EXTENSIONS: Array<string>
+
+    /**
+      Extensions that don’t map to routes but are elements that can be imported and used in routes.
+
+      @example
+      `component.js`, `component.ts`, `fragment.html`, `fragment.css`, `layout.js`, `layout.ts`
+
+      @see https://kitten.small-web.org/tutorials/components-and-fragments/
+    */
     DEPENDENCY_EXTENSIONS: Array<string>
+
+    /**
+      File extensions Kitten considers to be dynamic (not static) routes.
+
+      Currently, this includes all extensions in {@link BACKEND_EXTENSIONS} and {@link FRONTEND_EXTENSIONS}.
+    */
     DYNAMIC_ROUTE_EXTENSIONS: Array<string>
+
+    /**
+      Extensions for files that hold front-end functionality.
+
+      Currently: `page.js`, `page.ts`, and `page.md`.
+
+      @remarks For internal use only.
+    */
     FRONTEND_EXTENSIONS: Array<string>
+
+    /**
+      Extensions Kitten maps to standard HTTP routes.
+
+      @example
+      `get.js`, `post.js`, `put.js`, `head.js`, etc.
+
+      @see https://kitten.small-web.org/reference/#http-routes
+
+      @remarks For internal use only.
+    */
     HTTP_METHODS: Array<string>
+
+    /**
+      File extensions that that Kitten treats as static files.
+
+      Currently: `html` and `htm`.
+
+      @see https://kitten.small-web.org/tutorials/static-html/
+
+      @remarks For internal use only.
+    */
     STATIC_ROUTE_EXTENSIONS: Array<string>
+
+    /**
+      Given a file path, derives the unique class name for its route.
+
+      @remarks For internal use only.
+    */
     classNameFromFilePath: (filePath: string, basePath: string) => string
+
+    /**
+      Converts a route in the form of, e.g., `'/some_thing/with/underscores-and-hyphens'` to `'SomeThingWithUnderscoresAndHyphensPage'`.
+
+      @remarks For internal use only.
+    */
     classNameFromRoutePattern: (pattern: string) => string
+
+    /**
+      db namespace for JSDB database-related utility functions.
+    */
     db: {
+      /**
+        Given a JSDB change string, returns the dot-separated keypath of the changed property.
+      */
       keypathForChange(change: string): string
     }
+
+    /**
+      Inverse of encodeFilePath. Used when we want to avoid double escaping of file paths.
+    */
     decodeFilePath: (filePath: string) => string
+
+    /**
+      Since Polka does not handle unicode in paths correctly (see https://github.com/lukeed/polka/issues/187), we have to split the file path and URI encode each component ourselves.
+    */
     encodeFilePath: (filePath: string) => string
+
+    /**
+      Display error in console and exit process.
+
+      @remarks For internal use only.
+    */
     exitWithError: (message: string) => void
+
+    /**
+      Routes sorted by category based on their extensions (e.g., .page.js, post.js, etc.)
+
+      Routes in the different categories are served differently by Kitten.
+
+      @see https://kitten.small-web.org/reference/#valid-file-types
+
+      @remarks For internal use only.
+    */
     extensionCategories: {
       backendRoutes: Array<string>
       frontendRoutes: Array<string>
@@ -237,17 +695,64 @@ export interface KittenGlobal {
       staticRoutes: Array<string>
       allRoutes: Array<string>
     }
+
+    /**
+      Returns the complete extension (e.g., page.js not just .js) of the passed file path. Works with any number of extensions, returning the last two without a dot at the start.
+    */
     extensionOfFilePath: (filePath: string) => string
+
+    /**
+      Determines which places the server should listen at.
+    */
     getDomainsAndPort: (options: ServerOptions) => { domains: string[]; port: number }
+
+    /**
+      Returns unique project identifier based on the path of the project. This can be used as the name of a directory that is certain to be unique for this project.
+    */
     getProjectIdentifierForDomain: (domain: string, port: number) => string
+
+    /**
+      Kitten app path, formatted in a way that works regardless of whether Kitten was invoked using the `kitten` command from the bundled distribution or via _bin/kitten_ from source.
+    */
     kittenAppPath: string
+
+    /**
+      Run passed command (either `'ci'` or `'install'`) on the given module path.
+    */
     npm: (command: 'ci' | 'install', modulePath: string) => boolean
+
+    /**
+      Derives the route pattern for the passed file path based on the base path.
+    */
     routePatternFromFilePath: (filePath: string, basePath: string) => string
+
+    /**
+      Runs npm ci on the passed module path.
+    */
     runNpmCiOnModulePath: (modulePath: string) => void
+
+    /**
+      Calculates the base path used by the Kitten server to find files in the served app.
+    */
     setBasePath: (workingDirectory: string, pathToServe: string) => string
+
+    /**
+      A regular expression that matches all extensions supported by Kitten.
+
+      Currently, this includes all extensions in {@link DYNAMIC_ROUTE_EXTENSIONS} and {@link STATIC_ROUTE_EXTENSIONS}.
+
+      @remarks For internal use only.
+    */
     supportedExtensionsRegExp: RegExp
   }
 
+  /**
+    Constants for well-known/supported client-side libraries meant to be referenced in page routes.
+
+    Usually the file names held by these properties will refer to the minified version when `process.env.PRODUCTION` is `true` and non-minified versions otherwise (in development mode, so we can get more meaningful stack traces).
+
+    @see https://kitten.small-web.org/reference/#kitten-client-side-libraries
+  */
   libraries: {
     htmx: string
     htmxIdiomorph: string
@@ -256,6 +761,25 @@ export interface KittenGlobal {
     water: string
   }
 
+  /**
+    Special page slot names (constants) that can be used as targets of `<content for='…'>` tags.
+
+    @example
+    export default () => kitten.html`
+      <markdown>
+        # Special page slots
+
+        This is just regular page content.
+      </markdown>
+      <!-- Whereas this will be added to the <head>…</head> -->
+      <content for='${kitten.page.head}'>
+        <title>Special page slots</title>
+        <link rel='icon' href='/favicon.ico'>
+      </content>
+    `
+    
+    @see https://kitten.small-web.org/tutorials/special-page-slots/
+  */
   page: {
     html: 'HTML'
     head: 'HEAD'
@@ -265,24 +789,268 @@ export interface KittenGlobal {
     endOfBody: 'END_OF_BODY'
   }
 
+  /**
+    Use this method to add untrusted markup to your page safely.
+
+    You can customise the list of allowed tags by providing a list of ones to add to them (e.g., `['img']`) or by replacing it altogether with your own list by passing `false` as the last argument.
+
+    @example
+    <!-- Safely display comments on a blog that contain Markdown syntax. -->
+    <ul>
+      ${kitten.db.comments.map(comment => kitten.html`
+        <li>
+          <p>${kitten.safelyAddHtml(kitten.md.render(comment.message))}</p>
+          <p class='nameAndDate'>${comment.name} (${new Date(comment.date).toLocaleString()})</p>
+        </li>
+      `)}
+    </ul>
+
+    @remarks
+    Kitten escapes interpolated content by default so you’re safe from injection attacks by default. It also does not give you direct access to a `dangerouslySetInnerHTML()` style method on purpose. If you _really, really_ want to dangerously add HTML, you can do so by returning an array from your interpolation. e.g., `` `kitten.html`${[ thisContentWontBeSanitised ]}` ``. Needless to say, only ever do this with trusted content and then only if you absolutely must.
+  */
   safelyAddHtml: SanitisationFunction
+
+  /**
+    This is a wrapper around sanitize-html that you can use to only allow whitelisted HTML in strings.
+
+    @example
+    // Kitten’s `kitten.safelyAddHtml()` function uses `sanitise()`.
+    kitten.safelyAddHtml = (untrustedContent, allowedTags = [], concat = true) => kitten.html`${[ sanitise(untrustedContent, allowedTags, concat) ]}`
+
+    @see https://github.com/apostrophecms/apostrophe/tree/main/packages/sanitize-html
+  */
   sanitise: SanitisationFunction
 
+  /**
+    Reference to `WebSocket` class from ws.
+
+    Use it to create your own server-to-server WebSocket connections.
+
+    @see https://github.com/websockets/ws
+
+    @example
+    // Detail of _updates.socket.js_ route in Kitten’s Streamiverse example.
+    stream = new kitten.WebSocket('wss://streamiverse.small-web.org/stream.socket')
+
+    stream.addEventListener('message', event => {
+      const message = JSON.parse(event.data)
+      if (message.event === 'update') {
+        const post = JSON.parse(message.payload)
+
+        console.info(`  🐘 Got an update from ${post.account.username}!`)
+      }
+    })
+  */
   WebSocket: typeof KittenWebSocket
 
+  /**
+    Kitten is run by default to silence Node’s deprecation warnings (you can turn them on by running `kitten` with `SHOW_DEPRECATION_WARNINGS=true`) as we use experimental features and we don’t what the console output to be noisy.
+
+    Any deprecation warnings that are encountered are kept here even if they’re not shown in the console.
+
+    @see https://codeberg.org/kitten/app/src/branch/main/suppress-experimental.cjs
+  */
   deprecationWarnings: Array<string>
 
+  /**
+    File system paths of important Kitten resources.
+  */
   paths: {
+    /**
+      Absolute local system path for binaries (~/.local/bin)
+    */
+    BINARY_HOME: string,
+
+    /**
+      Path to Kitten’s own “binary” (shell script that starts the Node runtime and loads the loader and main process bundles).
+    */
+    KITTEN_BINARY_PATH: string,
+
+    /**
+      The path where a person’s data files should be stored according to the XDG Base Directory Specification (if the `XDG_DATA_HOME` environment variable is set, otherwise, falls back to _~/.local/share_).
+
+      @see https://specifications.freedesktop.org/basedir/latest/
+    */
+    DATA_HOME: string,
+
+    /**
+      The small-tech.org namespace within the person’s data home folder.
+
+      All Small Technology Foundation tools, including Kitten, live under this namespace.
+    */
+    SMALL_TECH_DATA_HOME: string,
+
+    /**
+      The home directory of Kitten’s own data.
+
+      Set to {@link SMALL_TECH_DATA_HOME}/kitten
+    */
+    KITTEN_DATA_HOME: string,
+
+    /**
+      The directory that hosts the Kitten app itself.
+
+      Set to {@link KITTEN_DATA_HOME}/app
+    */
+    KITTEN_APP_DIRECTORY_PATH: string,
+
+    /**
+      The directory containing Kitten’s own web app (settings, initial secret creation, etc.)
+
+      Set to {@link KITTEN_APP_DIRECTORY_PATH}/web
+    */
+    KITTEN_WEB_APP_DIRECTORY_PATH: string,
+
+    /**
+      The directory that houses all the TLS certificate information for Kitten servers (both local and globally-accessible ones).
+
+      Stores certificate data managed by \@small-tech/auto-encrypt (Let’s Encrypt) and \@small-tech/auto-encrypt-localhost, as abstracted by \@small-tech/https.
+
+      @see https://codeberg.org/small-tech/https
+    */
+    KITTEN_TLS_DIRECTORY: string,
+
+    /**
+      Contains certificate data for localhost domains.
+
+      As managed by Auto Encrypt Localhost (\@small-tech/auto-encrypt-localhost).
+
+      @see https://codeberg.org/small-tech/auto-encrypt-localhost
+    */
+    KITTEN_TLS_LOCAL_CERTIFICATE_DIRECTORY: string,
+
+    /**
+      Contains certificate data for production domains (and Web Numbers/IP Addresses).
+
+      As managed by Auto Encrypt (\@small-tech/auto-encrypt).
+
+      @see https://codeberg.org/small-tech/auto-encrypt
+    */
+    KITTEN_TLS_GLOBAL_CERTIFICATE_DIRECTORY: string,
+
+    /**
+      Location under /tmp that Kitten stores its temporary files.
+
+      Currently /tmp/small-tech.org/kitten
+    */
+    KITTEN_TEMP_DIRECTORY: string,
+
+    /**
+      Location of runtime.tar.xz, the archived version of Kitten’s runtime.
+
+      (Currently, Node.js).
+    */
+    KITTEN_TEMP_RUNTIME_ARCHIVE_PATH: string,
+
+    /**
+      The same-device temp directory is guaranteed to be on the same device as the rest of Kitten’s data so you can use, for example, `fs.rename` on it while you may not be able to do so with `KITTEN_TEMP_DIRECTORY`, which might be on a different partition.
+    */
+    KITTEN_SAME_DEVICE_TEMP_DIRECTORY: string,
+
+    /**
+      This directory holds Kitten’s runtime (currently, Node.js)
+    */
+    KITTEN_RUNTIME_DIRECTORY: string,
+
+    /**
+      The directory that holds the binary of Kitten’s runtime (currently, Node.js)
+    */
+    KITTEN_RUNTIME_BIN_DIRECTORY: string,
+
+    /**
+      The directory that holds the data for all projects (sites/apps) that have been served on this device.
+
+      Subfolders within this directory are named based on {@link utils.getProjectIdentifierForDomain}.
+    */
+    KITTEN_DATA_DIRECTORY: string,
+
+    /**
+      Kitten has two different types of internal databases: a global one for Kitten itself and separate internal databases for every project.
+
+      This is path for the global one.
+
+      @remarks For internal use only.
+    */
+    KITTEN_GLOBAL_INTERNAL_DATABASE_DIRECTORY: string,
+
+    /**
+      The directory that kitten projects are deployed to when you use the `kitten deploy` command.
+    */
+    KITTEN_DEPLOYMENTS_DIRECTORY: string,
+
+    /**
+      The directory that the repositories are cloned to when you use the `kitten run` command to clone and run a Kitten project based on the HTTPS git URL of the project’s repository.
+    */
+    KITTEN_CLONES_DIRECTORY: string,
+
+    /**
+      The path where a person’s configuration files should be stored according to the XDG Base Directory Specification (if the `XDG_CONFIG_HOME` environment variable is set, otherwise, falls back to _~/.config_).
+
+      @see https://specifications.freedesktop.org/basedir/latest/
+    */
+    CONFIG_HOME: string,
+
+    /**
+      Path of the systemd “user” (we don’t use that term in Small Tech as it’s an othering) directory.
+
+      Defaults to _~/.config/systemd/user_.
+    */
+    SYSTEMD_USER_DIRECTORY: string,
+
+    /**
+      Path to Kitten’s systemd unit.
+
+      Set to {@link SYSTEMD_USER_DIRECTORY}/kitten.service
+    */
+    KITTEN_SYSTEMD_UNIT_PATH: string
+
+    // From Kitten’s src/lib/globals.ts
+
+    /**
+      The app data directory for the current app (site/project).
+
+      Set to the return value of {@link utils.getProjectIdentifierForDomain} in {@link KITTEN_DATA_DIRECTORY}.
+    */
     APP_DATA_DIRECTORY: string
+
+    /**
+      The location of file uploads for the current app.
+
+      Set to {@link APP_DATA_DIRECTORY}/uploads
+    */
     APP_UPLOADS_DIRECTORY: string
+
+    /**
+      The location of REPL data (REPL history) for the current app.
+
+      Set to {@link APP_DATA_DIRECTORY}/repl
+    */
     APP_REPL_DIRECTORY: string
   }
 
+  /**
+    For internal use by Kitten’s web app.
+  */
   deploy: Function
 }
 
 declare global {
-  var kitten: KittenGlobal
+  /**
+    Kitten’s global `kitten` object.
+
+    The most common properties you’ll be using in daily authoring include:
+
+      - {@link html}          - Write HTML with component and string interpolation support.
+      - {@link db}            - Reference your site/apps custom JSDB database.
+      - {@link Page}          - Extend this class to create your own Kitten pages.
+      - {@link Component}     - Extend this class to create your own stateful Kitten components.
+      - {@link safelyAddHtml} - Use when adding untrusted content to your pages.
+      - {@link crypto}         - Kitten’s cryptographic library.
+      - {@link icons}         - Kitten’s built-in icon library.
+
+    @see https://kitten.small-web.org/tutorials/
+  */
+  var kitten: kitten
 }
 
 export {}