Cognikit

Cognikit is a browser-first toolkit for building cognitive and educational interactions: classification, recall, recognition, text activities, and table-based tasks.

It gives you two main integration styles:

• shell + interaction: use the built-in shell for prompt display, timer, progress, retry, score, and navigation.
• shell-less interaction: mount an interaction directly and manage the surrounding UI yourself.

What It Includes

• Built-in interaction classes such as OpenClassification, SequentialClassification, MCQ, ListRecall, RankOrder, text interactions, and table interactions.
• createInteraction(id, data, config, assets) for runtime creation from a registry id.
• InteractionsBaseShell for a ready-made interaction container.
• Asset parsing and validation helpers.
• Theme and audio configuration helpers.
• SSR compatibility guards for browser-oriented environments.

Install

pnpm add cognikit

Basic Setup

The package is browser-oriented. In frameworks like React or Next.js, create and mount interactions inside a client-side effect.

import * as cognikit from "cognikit";

cognikit.configureCognikit({
  audioBaseUrl: "/assets/audio/",
  theme: "default-light",
});

Quick Start: Shell + Interaction

This is the recommended path if you want the packaged UX.

import * as cognikit from "cognikit";

const shell = new cognikit.InteractionsBaseShell();

const data = {
  type: "sequential-classification",
  categories: [
    { label: "Ocean", items: ["Dolphin", "Shark", "Octopus"] },
    { label: "Land", items: ["Lion", "Elephant", "Tiger"] },
    { label: "Air", items: ["Eagle", "Parrot", "Hawk"] },
  ],
};

const config = {
  prompt: "Sort the animals by habitat",
  variant: "elegant",
  shuffle: true,
  attemptLimit: 2,
  timer: 120,
  animationsEnabled: true,
  soundEnabled: true,
};

const interaction = cognikit.createInteraction(
  "sequential-classification",
  data,
  config,
  null,
);

shell.setInteraction(interaction);
document.body.appendChild(shell);

What the shell gives you

• Prompt header
• Timer
• Progress bar
• Check / retry controls
• Score screen
• Sequential navigation for interactions that expose steps
• Basic error screen for invalid interactions

Shell-less Interactions

If you want full control over layout and surrounding controls, mount the interaction directly.

import { ListRecall } from "cognikit";

const interaction = new ListRecall(
  {
    type: "seriation",
    items: ["Passport", "Wallet", "Keys", "Phone"],
  },
  {
    prompt: "Recall the travel checklist",
    variant: "minimal",
    shuffle: false,
    attemptLimit: 1,
    timer: null,
    animationsEnabled: true,
    soundEnabled: true,
  },
);

document.querySelector("#app")?.appendChild(interaction);

Use shell-less mode when:

• you already have your own timer / scoring UI
• you want to embed interactions into an existing app layout
• you want tighter control over fullscreen, dialogs, or analytics

Assets

Some interactions and prompts can reference assets such as images, video, audio, HTML, or TTS.

YAML assets

butterfly:
  type: image
  url: https://example.com/butterfly.jpg

intro_audio:
  type: audio
  url: https://example.com/intro.mp3
  volume: 80

Parse and validate

import { parseYamlAssets, validateAndNormalizeAssets } from "cognikit";

const yaml = `
butterfly:
  type: image
  url: https://example.com/butterfly.jpg
`;

const assets = validateAndNormalizeAssets(parseYamlAssets(yaml));

If validation fails, Cognikit throws AssetValidationError.

To be able to use these assets in an interaction, you need to set <@:assetName> in the data value.

const assets = ...;

// supposing you have a asset name called "phone"
const data = {
    type: "seriation",
    items: ["Passport", "Wallet", "Keys", "@:phone"],
};

Configuring Theme

Cognikit exposes preset themes and theme variable overrides.

import { configureCognikit } from "cognikit";

configureCognikit({
  theme: "default-dark",
});

Available built-in themes:

• default-light
• default-dark
• ocean-light
• ocean-dark
• forest-light
• forest-dark

Custom theme variables

configureCognikit({
  theme: "default-light",
  themeVariables: {
    "--edu-first-accent": "124 58 237",
    "--edu-radius": "0.75rem",
    "--edu-card": "255 255 255",
  },
});

Theme helpers

You can also use:

• ensureCognikitTheme()
• getCognikitConfig()
• getCognikitThemePresets()
• resolveCognikitTheme()
• setCognikitTheme()
• resetCognikitTheme()
• defaultCognikitThemeVariables
• cognikitThemePresets

Configuring Audio

Built-in shell and interaction sounds resolve through Cognikit config.

configureCognikit({
  audioBaseUrl: "/assets/audio/",
});

You can also override named sound files:

configureCognikit({
  audioBaseUrl: "/assets/audio/",
  soundFiles: {
    start: "custom-start.mp3",
    success: "custom-success.mp3",
    failure: "custom-failure.mp3",
  },
});

Interaction Setup

Most interactions use the same setup pattern:

1. Prepare data
2. Prepare config
3. Optionally parse and validate assets
4. Create the interaction
5. Mount it directly or pass it into InteractionsBaseShell

Data types

Cognikit currently exposes these base data shapes:

• ClassificationData
• AssociationData
• RecognitionData
• SeriationData
• FreeRecallData
• table data types
• text engine data types

Example configs

const config = {
  prompt: "Arrange the butterfly life cycle",
  variant: "outline",
  shuffle: true,
  attemptLimit: 2,
  timer: 180,
  animationsEnabled: true,
  soundEnabled: true,
};

Important config fields:

• prompt
• variant
• shuffle
• attemptLimit
• timer
• animationsEnabled
• soundEnabled
• promptModality
• promptData
• promptDataSpec

Built-in Interaction Registry IDs

These ids are registered out of the box and work with createInteraction(...):

• open-classification
• sequential-classification
• mcq
• simultaneous-association
• list-recall
• lookup-table
• classification-matrix
• nary-choice-table
• adjacency-table
• mark-the-words
• sequential-mark-the-words
• categorize-the-words
• sequential-categorize-the-words
• text-transformation
• sequential-text-transformation
• fill-blanks
• sequential-fill-blanks
• rank-order

Recommended Imports

General use

import * as cognikit from "cognikit";

Named imports

import {
  createInteraction,
  InteractionsBaseShell,
  configureCognikit,
  parseYamlAssets,
  validateAndNormalizeAssets,
} from "cognikit";

Client-focused entry

import * as cognikit from "cognikit/client";

The client entrypoint ensures built-ins are registered and theme variables are applied immediately in client-only usage.

React / Next.js Notes

• Use Cognikit inside a client component.
• Mount shells and interactions inside useEffect.
• If you switch between dark and light site themes, call configureCognikit({ theme: ... }) when the app theme changes.
• If you want fullscreen previews, it is usually cleaner to create a second shell instance for the overlay rather than moving the same DOM node around.

Project Structure

High-level layout:

src/
  core/           Base interaction primitives
  interactions/   Built-in interaction classes and registry
  engines/        Text and table engines
  shell/          Shell UI
  shared/         Config, assets, utils, managers
  types/          Public types
  ui/             Reusable custom elements
public/
  index.html
  app.js
  demo assets

Key files:

• src/index.ts: primary package entrypoint
• src/client.ts: client-focused entrypoint
• src/interactions/register-builtins.ts: built-in registry ids
• src/shared/config.ts: theme and audio configuration
• src/shared/assets.ts: asset validation

Local Development

pnpm install
pnpm dev

Useful scripts:

• pnpm build
• pnpm build:lib
• pnpm build:demo
• pnpm types
• pnpm serve

License

MIT