/**
  Kitten types.

  Type declarations for global `kitten` namespace.
*/

import type { EventEmitter } from 'node:events'
import type { Server } from 'node:https'
import type { AutoEncryptedServer } from '@small-tech/auto-encrypt'
import type { AutoEncryptedLocalhostServer } from '@small-tech/auto-encrypt-localhost'

import type {
  Session,
  Upload,
  KittenComponent,
  KittenPage,
  MarkdownIt,
  Polka,
  WebSocket as KittenWebSocket,
  slugify as Slugify,
  yaml as Yaml,
  Point,
  Signature
} from './types.d.ts'

import type { KittenIcons } from 'kitten-icons/types.d.ts'

/**
  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`).
*/
export type SanitisationFunction = (
  untrustedContent: string,
  allowedTags?: Array<string>,
  concat?: boolean
) => string | Array<string> | Promise<string | Array<string>>

/**
  Record that maps URL fragments to hit counts.
*/
type StatsObject = Record<string, number>

/**
  Internal Kitten database (`kitten._db`).
*/
export interface KittenInternalDatabase {
  sessions: Record<string, Session>
  settings: {
    autoUpdate: {
      interval: number
    }
    domainToken: string
    domainRedirects: Record<string, string>
    localRedirects: Record<string, string>
    evergreenWebUrl: string
    hideWelcomeMessage: boolean
    id: {
      ed25519: {
        asString: string
      }
      ssh: {
        asString: string
        fingerprint: string
      }
      pgp?: {
        asString: string
      }
    }
    path: string
    smallWebHostDomain: string
    webhookSecret: string
  }
  packageLockFileHashes: Record<string, string>
  stats: {
    hits: StatsObject
    pages: StatsObject
    missing: StatsObject
    referrers: StatsObject
    serverErrors: StatsObject
  }
  uploads: UploadStore,
  scheduledRestart: {
    lastRestartDate: number
    restartHour: number
  }
}

/**
  The `kitten.uploads` store.
*/
export type UploadStore = {
  get(id: string): Upload
  length(): number
  all(): Upload[]
  allIds(): string[]
  delete(id: string): Promise<void>
} & Record<string, Upload>

/**
  Configuration options for the Kitten server.
*/
interface ServerOptions {
  domain?: string
  port?: number
  aliases?: string
  open?: boolean
  'working-directory'?: string
  'domain-token'?: string
  'small-web-host-domain'?: string
}

type UpdateType = 'upgrade' | 'downgrade' | 'updating' | 'restarting'

/**
  Conditionally-active logger.

  Logs a message when enabled (via the `LOG` environment variable, the runtime control methods, or while the Kitten REPL is active for REPL loggers).
*/
export type Logger = ((...args: unknown[]) => void) & { enabled: boolean }

/**
  Names of log sections used by Kitten.
*/
export type LogSection =
  | 'lifecycle' | 'event' | 'streamingHtml' | 'repl' | 'debug'
  | 'router' | 'html' | 'watcher' | 'pageSocketRoute'
  | 'webSocketRoute' | 'verbose'

/**
  Kitten’s logging namespace, exposed at `kitten.log`.

  Exposes one {@link Logger} per {@link LogSection} plus runtime controls to enable/disable loggers and display logging information.
*/
export interface Log extends Record<LogSection, Logger> {
  /** Whether any logger is currently enabled. */
  isActive: boolean
  /** Prints the key of symbols used in log prefixes. */
  showKey: () => void
  /** Lists the currently enabled loggers. */
  listEnabled: () => void
  /** Enables all loggers. */
  all: () => void
  /** Alias for {@link all}. */
  on: () => void
  /** Enables only the specified loggers, disabling the rest. */
  only: (...loggers: LogSection[]) => void
  /** Disables all loggers. */
  none: () => void
  /** Alias for {@link none}. */
  off: () => void
  /** Whether the log key has already been shown. */
  keyAlreadyShown: boolean
}

/**
  Global `kitten` namespace.
*/
export interface kitten {
  /**
    Kitten’s version number and releated utilities.
  */
  version: {
    date: Date
    versionStamp: number
    gitHash: string
    apiVersion: number
    nodeVersion: string
    exactVersion: string
    birthday: string
    starSign: string
    Component: () => Function
    html: () => string
    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
    // Note: Type 'Polka' *is* generic. If you’re seeing an error to the contrary, the type checker is picking up more recent type information for Polka from its @types package from a global typescript install.
    // `router` and `server` are wired up incrementally after the `app` object is first created (as `{}`) in `globals.ts`, hence optional.
    router?: Polka<any>
    server?: Server | AutoEncryptedServer | AutoEncryptedLocalhostServer
  }

  /**
    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

  /**
    Kitten’s internal database.

    You should not need to access this directly.
  */
  _db: KittenInternalDatabase

  /**
    Kitten’s global internal database.

    Unlike Kitten’s internal and app databases, this database is scoped to the Kitten instance, *not* to the app that Kitten is serving.

    You should not need to access this directly. (That’s two underscores to – uhum – underscore the fact. 👻)
  */
  __db: import('../GlobalInternalDatabase.ts').GlobalInternalDatabaseType

  /**
    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

  /**
    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

  /**
    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?: {
    latestCompatibleVersion?: string,
    latestVersion?: string,
    latestApiVersion?: number,
    manualUpdateAvailable?: boolean,
    originRemoteUrl?: string,
    currentVersion?: string,
    latestAvailableCommit?: string,
    upgradeAppToLatestCompatibleVersion(): Promise<void>
    upgradeAppToLatestAvailableCommit(): Promise<void>
    updateAppToVersion(versionTag: string): Promise<void>
    update(): Promise<void>
    hasCompatibleAppVersion: boolean
    canBeUpgraded: boolean
    hasNewerApiVersion: boolean
    upgradeOrDowngrade(versionTag: string, lowercase: boolean): 'upgrade' | 'Upgrade' | 'downgrade' | 'Downgrade' | false
    isEqualToVersion(versionTag: string): boolean

    /** Returns a configured update button component. */
    UpdateButtonComponent(): ({type, version, small}: { type?: UpdateType, version?: string, small?: boolean }) => ReturnType<TaggedTemplate>

    VersionComponent ({version, compatible, brief}: { version: string, compatible: boolean, brief: boolean}): ReturnType<TaggedTemplate>

    /** Returns a configured Current app version component. */
    CurrentAppVersionComponent(): () => ReturnType<TaggedTemplate>

    /** Returns a configured All available versions component or kitten.html (it probably shouoldn’t be doing that). */
    AllAvailableVersionsComponent(): (() => ReturnType<TaggedTemplate>) | ReturnType<TaggedTemplate>
    displayAppVersion(): void
  }

  /**
    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
    timeToNextCheckPretty(): string | number
    start(): void
    checkForUpdates(): Promise<void>
    stop(): void
  }

  /**
    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
    isMoreRecentThanReleaseVersion: boolean
    canBeUpgraded: boolean
    upgrade(apiVersion?: number): void
    update(): Promise<void>,
    latestRecommendedVersion?: {
      versionStamp: number,
      gitHash: string,
      apiVersion: number,
      nodeVersion: string,
      exactVersion: string,
      buildDate: Date,
      releaseDate: Date,
      upload: Upload,
      _buildDate:string,
      _releaseDate:string
    }
  }

  /**
    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 ciphertext (nonce ‖ ciphertext, hex-encoded string or raw bytes)
      using the shared key (XChaCha20-Poly1305 via @noble/ciphers).

      @see https://www.npmjs.com/package/@noble/ciphers
    */
    decrypt: (sharedKey: Uint8Array, encoded: string | Uint8Array) => Promise<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
      (XChaCha20-Poly1305 with a random 24-byte nonce via @noble/ciphers).

      @returns nonce ‖ ciphertext as bytes.

      @see https://www.npmjs.com/package/@noble/ciphers
    */
    encrypt: (sharedKey: Uint8Array, plaintext: string | Uint8Array) => Promise<Uint8Array>

    /**
      Encrypts a message for a domain.

      @param message Message to encrypt
      @param ourPrivateKey Our emoji-encoded private key (or the raw 32-byte secret)
      @param domain The domain to encrypt the message for
      @returns Versioned envelope: `v2:` followed by the hex-encoded nonce ‖ ciphertext.

      @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 | Uint8Array, domain: string) => Promise<string>

    /**
      Converts ed25519 private / public keys to Curve25519 and calculates Elliptic Curve Diffie Hellman (ECDH) with X25519. Conforms to RFC7748.

      Returns the raw Diffie-Hellman output. Prefer {@link sharedSecretForDomain},
      which additionally applies HKDF-SHA-256.
    */
    getSharedSecret: (
      privateKey: Uint8Array | string,
      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
      (X25519 Diffie-Hellman key agreement followed by HKDF-SHA-256, via Web Crypto).

      Part of the Meow Protocol.
    */
    sharedSecretForDomain: (domain: string, ourPrivateKey: string | Uint8Array) => Promise<Uint8Array>

    /**
      Signs message with private key and returns EdDSA signature.

      Uses the platform’s Web Crypto API (Ed25519).

      @param message Message (not message hash) which would be signed (raw bytes or hex-encoded string)
      @param privateKey Private key which will sign the message (raw bytes, hex-encoded string, or a Web Crypto CryptoKey)
      @returns EdDSA signature (64 bytes).
    */
    sign: (message: Uint8Array | string, privateKey: Uint8Array | string | CryptoKey) => Promise<Uint8Array>

    /**
      Verifies signature.

      Uses the platform’s Web Crypto API (Ed25519).

      @param sig Signature returned by {@link sign} function (raw bytes or hex-encoded string)
      @param message Message to be verified (raw bytes or hex-encoded string)
      @param publicKey Public key (raw bytes, hex-encoded string, or a Web Crypto CryptoKey)

      @returns `true` if the signature is valid, `false` otherwise (including for malformed inputs).
    */
    verify: (
      sig: Uint8Array | string,
      message: Uint8Array | string,
      publicKey: Uint8Array | string | CryptoKey
    ) => 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>
      dependencies: Array<string>
      dynamicRoutes: Array<string>
      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) => Promise<{ domains: string[]; port: number | boolean }>

    /**
      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: string
  }

  /**
    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
    htmxWebSocket: string
    alpineJs: string
    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'
    startOfBody: 'START_OF_BODY'
    beforeLibraries: 'BEFORE_LIBRARIES'
    afterLibraries: 'AFTER_LIBRARIES'
    endOfBody: 'END_OF_BODY'

    // Common aliases/miscapitalisations added at runtime to be more forgiving
    // during authoring. Optional because they are set after the base object
    // literal is first assigned in `globals.ts`.
    HTML?: 'HTML'
    Html?: 'HTML'
    HEAD?: 'HEAD'
    Head?: 'HEAD'
    START_OF_BODY?: 'START_OF_BODY'
    StartOfBody?: 'START_OF_BODY'
    startofbody?: 'START_OF_BODY'
    AFTER_LIBRARIES?: 'AFTER_LIBRARIES'
    AfterLibraries?: 'AFTER_LIBRARIES'
    afterlibraries?: 'AFTER_LIBRARIES'
    END_OF_BODY?: 'END_OF_BODY'
    EndOfBody?: 'END_OF_BODY'
    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

  /**
    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).

      Use when opening your database in a Database App Module to get the path to it.

      @example
      JSDB.open(
        path.join(kitten.paths.APP_DATA_DIRECTORY, 'db'),
        {
          compactOnLoad, 
          classes: [
            Database,
            Kitten
          ]
        }
      )

      @see https://kitten.small-web.org/tutorials/database-app-modules/
      @see https://codeberg.org/kitten/app/src/branch/main/examples/database-app-module/app_modules/database/database.js#L46
    */
    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

  /**
    Kitten’s built-in components.

    Contains both the stateless (function) and stateful (class) variants of each built-in component.
  */
  components: {
    /**
      Stateless copy-to-clipboard button component.
    */
    copyButton: typeof import('../lib/components/stateless/copyButton.component.ts')['default']

    /**
      Stateful copy-to-clipboard button component.
    */
    CopyButton: typeof import('../lib/components/stateful/CopyButton.component.ts')['default']

    /**
      Toast component.
    */
    toast: typeof import('../lib/components/stateless/toast.component.ts')['default']
  }

  /**
    Helper method: Returns value by applying keypath to passed object.

    @remarks For internal (debug/REPL) use only.
  */
  ___valueAtKeypath: (object: any, keypath: string) => any

  /**
    Easily listen for events on JSDB tables from the Kitten Interactive Shell (REPL).

    @remarks For debug-time use only. It does not remove listeners so should not be used in authored code.
  */
  $showEventsOnTable: (tableName: string, showPersistedChange?: boolean) => void

  /**
    The names of the tables in your custom JSDB database (`kitten.db`).

    @remarks For debug-time use only (e.g., from the Kitten Interactive Shell/REPL).
  */
  readonly $tables: Array<string>

  /**
    Kitten’s logger.

    Separates logs out by sections that can be enabled using the `LOG` environment variable (e.g. `LOG=event,lifecycle kitten` or `LOG='*' kitten`)  or toggled at runtime via `kitten.log.all()`, `kitten.log.none()`, and `kitten.log.only(…)`.
  */
  log: Log

  /**
    Tracks whether the Kitten REPL (interactive shell) is active.

    Used by loggers to emit additional information while the REPL is active.

    @remarks For internal use only.
  */
  __replIsActive: boolean
}

declare global {
  /**
    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 {}