Adaptive Palette

This project builds a palette that empowers AAC(Augmentative and Alternative Communication) users with the ability to personalize it according to their specific requirements, thereby enhancing their communication capabilities with others.

The front end of the project is built with Preact.

Two Versions

Adaptive Palette comes in two versions:

	Public website	Desktop version
Where	adaptive-palette.pages.dev	Installed on your computer — see Install on Your Computer
AI features	Off	On, with Ollama running on the same computer
Your messages and settings	Kept until the page is reloaded or closed; nothing is saved in the browser	Saved in the browser's IndexedDB on your computer

The public website is for trying Adaptive Palette without installing anything: the palette layout, Bliss input, and the other features that need no AI. It saves nothing because it may be opened on a shared or public computer.

The desktop version is for everyday use and protects your privacy. It saves your messages so the AI features can tailor their suggestions to you, and both that data and the AI models stay on your computer: nothing you write leaves it.

Install

To work on the project, you need to install NodeJS and NPM for your operating system.

Then, clone the project from GitHub. Create a fork with your GitHub account, then enter the following in your command line (make sure to replace your-username with your username):

git clone https://github.com/your-username/adaptive-palette

From the root of the cloned project, enter the following in your command line to install dependencies:

# Install project dependencies
npm ci

# Install Playwright browsers for testing. This should only need to be done once.
npx playwright install

Development

Start Development Server

To start a local development server with hot module reload that injects updated code modules directly into a running application without requiring a full page refresh, run:

npm start

The website will be available at http://localhost:3000.

To build the project for production (outputs to dist), run:

npm run build
npx vite preview

_NOTE: npx vite preview launches a local static web server to preview the build in the /dist directory.

Test the Public Website Version

The app runs as the public website version whenever the page is not opened from localhost, 127.0.0.1 or [::1]. In this version, model features are off, first-run setup is skipped, and nothing is saved in the browser.

To test it locally:

1. Start the server with --host so it is reachable on your network:

   # Development server
   npm start -- --host
   
   # Or the production build
   npm run build
   npx vite preview --host

2. Open the Network URL the server prints, such as http://192.168.1.6:3000/, instead of the localhost one.

NOTE: On macOS, if the Network URL shows a blank page while localhost works, the firewall is blocking Node. This happens when Node is not code-signed, such as Node installed by Homebrew. Use a signed Node from nodejs.org or nvm, then allow node when macOS asks to accept incoming connections.

Lint

To lint the source code, run:

npm run lint

Type Checking

To type check the source code, run:

npm run typecheck

Run Tests

To run tests, run:

# Run all tests
npm test

You can pass in arguments to the tests runner by placing them after a --. For example, if you want to only run a single test you could call npm test -- {test file name}.

For a complete list CLI flags that can be passed to the tests see Vitest's Command Line Interface docs.

NOTE: The browser tests make use of Playwright to test real browsers. If you haven't already, you may need to run npx playwright install to install browsers.

See Testing for the test setup, watch mode and running a single file.

Demonstrations

The sub-folder demos contains code for a number of demonstrations. These are short examples. The apps folder contains more fully built-out application examples. See the respective READMEs and documentation for instructions on how to run the software.

• Ollama Chat Web-App: a chat application running on localhost that provides access to multiple models using the Ollama localhost web service.
• Palette Generator Web-App: an application for generating and saving a palette using the Bliss gloss. By providing a set of gloss words, BCI AV IDs, or svg builder strings, the Bliss gloss is searched and a palette is generated based on matches found.
• Ollama Chat Service Demo: a simple web-app that runs on localhost for sending queries to an Ollama chatbot service also running on localhost.

Cloudflare

The adaptive-palette can be served as a production preview using Cloudflare Pages, specifically using the Git integration guide. You will need to have your own Cloudflare account to do this.

In the "Deployment details" for the preview, use the following for the "Build command" and "Build output directory" settings:

• Build command: npm run build
• Build output directory:: /dist

Documentation

Feature Documentation

• Label Lookup When Indicator Applied: three-stage pipeline that maps every symbol+indicator pair that the vocabulary supports to its grammatically correct label.
  • Corresponding script directory
• Telegraphic Message Translation: use a local Ollama model to turn telegraphic messages into complete, speakable English sentences.
• Word Prediction: suggest the words most likely to come next, from the user's past messages and optionally from a local Ollama model.
• Adjust Settings: change the runtime settings from within the app, saved in the browser and applied at the next page load.
• About Me: notes about the user that sentence and word suggestions use, typed in or accepted from the AI model's suggestions. Desktop version only.
• Access Methods: use the palette with a keyboard, mouse, touch or two switches, and how they work together.
• Install on Your Computer: install Adaptive Palette and Ollama on macOS or Windows, run it for the first time, and uninstall it cleanly.

Utility Documentation

• Shortcut Keys: keyboard shortcuts for palette navigation, caret movement in the input area, and modal dialogs.
• Generate Bliss Symbol Explanations: how to generate public/data/bliss_symbol_explanations.json, which contains Bliss symbol vocabulary including glosses, part-of-speech labels, semantic explanations, and symbol compositions.
  • Corresponding utility script
• Palette JSON Generator: how to use the web-based Palette Generator app to create custom Bliss symbol palettes from gloss words, BCI AV IDs, or SVG builder strings.
  • Script directory

Developer Documentation

• Developer Documentation: technical guide for developers building the adaptive palette. Covers the source structure, application state, runtime configuration, palettes, cell types, Bliss sentences and testing, testing, and desktop packaging.

Attribution

The following data file is adapted from Blissary.com, which builds upon the work of Blissymbolics Communication International (BCI).

In accordance with the ShareAlike clause, this adapted file is also licensed under CC BY-SA 4.0:

• public/data/bliss_symbol_explanations.json

Acknowledgments

This project was developed using an AI-assisted workflow. Special thanks to Claude Code and OpenAI Codex. All AI-generated code was reviewed, tested, and refined by human developers to ensure quality and security.