#+title: Nitinol
#+options: toc:nil

Nitinol is a framework for building user-malleable web applications and tools, specifically PWAs, built on top of [[https://mithril.js.org/index.html][Mithril.js]] and [[https://lips.js.org/][LIPS scheme]].
It provides all the tools necessary to make a full application stack that the user is easily able to modify; both for themselves or others, and ephemerally or persistently.

#+begin_quote
Nitinol is an alloy of Nickel and Titanium that has shape memory and superelasticity.
#+end_quote

This README includes all the documentation you need to use Nitinol to it's fullest.
If you're not sure how to read ~org~ files, you can convert this file to Markdown with pandoc using the following command:
#+begin_src shell
  pandoc -f org -t makrdown README.org
#+end_src

#+toc: headlines 2

* Design Philosophy
Nitinol is heavily inspired by Emacs in terms of extensibility and self-documentation.
Instead of treating the application as a standalone application, it should be treated as a construction on top of a powerful Lisp core.
This core can then be modified by the user in real time --- allowing them to almost entirely change application behaviour --- or inspected to easily understand the inner workings.

A number of approaches already exist on the web for achieving malleability, but they are nothing compared to the power of a proper scripting engine.
- Settings only allow the user to modify the application in ways made legal by the original developer.
- Plugins also have limits in their ability to modify aspects of the application, while also generally being difficult to develop.
- Extensions can inject CSS or HTML but cannot modify server-side behaviour, and can also be annoying to develop and share.
- Open source projects typically lack sufficient internal documentation for non-developers to modify the internals, and often require additional (possible painful) setup steps.

Nitinol seeks to address all these problems by providing a Scheme environment in the web browser, and tools for building full applications.
- A live REPL allows the user to modify the application in real time.
- REPL inputs can be saved to a cached configuration file, which can be shared to other users of the application.
- Code is self-documenting via doc string macros and source code links, allowing easy introspection.
- Both the front-end and back-end can be modified (within security and access control constraints).

* Using Nitinol
Nitinol is a project template, you can use it simply by cloning this repo and modifying its content.

If you're new to Node.js development, start with ~npm i~ to install all dependencies.
You may also wish to install LIPS globally with ~npm -g install lips~, which will allow you to run a local repl with the ~lips~ command.
This is not required to use this framework, but is recommended.

You should also run ~npm run nitinol:update~ to pull in the Nitinol library files.

Then, the command ~npm run preview~ will start the backend and frontend.

* Getting Started

** Project Structure
There are 3 main folders in this template that you should pay attention to.
- ~app~ contains all frontend application code, including HTML, CSS, and manifest/JS code necessary for a PWA.
  - ~app.scm~ in the ~app~ directory is the entry point for the Nitinol application - i.e. the script that is loaded by the HTML template.
  - The Nitinol libraries are made automatically available to ~app.scm~ via a script tag in the HTML template.
- ~server~ contains all backend server code, with the ~server.scm~ file being the entry point used to start the backend.
- ~lib~ contains libraries potentially shared between the front and back end, as well as [[https://git.cyan.sh/BirDt/nitinol][Nitinol]] LIPS libraries included as a git submodule.
  - ~npm run nitinol:update~ will update the Nitinol submodule.