kireji 0.0.1

package/docs/ARCHITECTURE.md

@@ -0,0 +1,90 @@
+# kireji – Architecture Overview
+
+This document provides a technical deep dive into the inner workings of kireji. It supplements the main README with details on the hashing model, URL compression strategy, and state representation.
+
+---
+
+## 1. Minimal Perfect Hashing
+
+kireji employs a piecewise-defined, recursive **minimal perfect hash function (MPHF)** to compress part state information into compact, shareable URLs. Each application state is represented as a natural number $`n`$, with the MPHF ensuring a 1:1 mapping between $`n`$ and its respective part state configuration.
+
+### 1.1 Bijection Model
+
+The core mapping is:
+
+```
+n <--> Part State
+```
+
+Each part declares its cardinality $`k`$, which defines the number of possible states it can occupy. The system ensures that every part maps deterministically to a unique number $`0 < n < k`$ within its cardinality range.
+
+### 1.2 URL Path Encoding
+
+Each full application state is encoded into a URL using variable-length base-64 segments. A typical path looks like:
+
+```
+https://www.example.com/ghc3w_hi4-5g4w3/
+```
+
+Each segment represents a portion of the application's state tree. Path segments can store \~1500 bits of entropy each, using the geometric series:
+
+$$
+k_{segment} = (64^{251} - 64)/63 ≈ 2^{1500}
+$$
+
+This provides extremely dense representation of state without relying on query parameters or local storage, making states sharable and deep-linkable by permanent URLs.
+
+## 2. Part Model and State Composition
+
+### 2.1 Mix and Match Parts
+
+kireji models state as a recursive tree:
+
+* `mix.core.parts` performs **multiplicative composition** (Cartesian product of independent subparts)
+* `match.core.parts` performs **additive composition** (exclusive options / partitioning)
+
+These two operations enable arbitrarily complex state spaces to be built from small, reusable parts.
+
+### 2.2 Stateful Behavior
+
+Each part reads and writes its state as an integer. This state is derived from the states of its subparts or from local input, and any mutation automatically updates its hash value.
+
+Example mapping:
+
+```
+https://two-digit.example.com/v123/0t
+-> [domain: two-digit.example.com, version: 123, state: 94]
+-> subpart mapping: [tensPlace.routeID = 9, onesPlace.routeID = 4]
+```
+
+## 3. State Propagation
+
+kireji supports rootward and leafward propagation of state changes. Any state mutation in a subpart triggers a full recalculation of parent route identifiers up to the DNS root. This model ensures full consistency across nested part hierarchies.
+
+The URL in the address bar always reflects the root part's state and is updated at throttled intervals (to align with browser frame rate limits and avoid DoS mitigation mechanisms).
+
+## 4. Prototype Tree and Inheritance
+
+Each domain maps to a runtime object (called a part), and subdomains define subparts. These parts follow a prototype-based inheritance model:
+
+* Domains can extend other domains
+* Behaviors and cardinalities are inherited or overridden
+* The root prototype is `part.core.parts`
+
+This system enables reuse and modularity while preserving static determinism.
+
+## 5. Current DNS Integration Status
+
+DNS-based behaviors are currently **modeled only**:
+
+* TXT record fetching is implemented in a commented-out form
+* No live production use of DNS records occurs yet
+* This modeling forms the basis for future decentralized architecture
+
+---
+
+## Summary
+
+kireji's architecture is defined by its emphasis on stateless, composable, mathematically rigorous component modeling. The hash function acts as the universal interface for state storage, navigation, and sharing, enabling a new paradigm for front-controlled applications without traditional backends.
+
+For build engineers, architects, and researchers, kireji offers a reproducible and self-contained environment to explore scalable UI logic, compressed state modeling, and reactive full-stack design.

package/docs/ENVIRONMENTS.md

@@ -0,0 +1,89 @@
+# kireji – Runtime Environment Model
+
+This document provides an overview of the three runtime environments supported by kireji. It outlines how the framework maintains consistency, reactivity, and optimal performance across the entire stack - from build time to client interaction.
+
+---
+
+## Overview of the Three Environments
+
+kireji is designed to operate identically across three distinct environments:
+
+1. **`server` (Creates a backend via Node.js)**
+2. **`worker` (Creates a local backend via Service Worker)**
+3. **`client` (Creates the GUI in a browser window)**
+
+Each environment has unique responsibilities, but they all operate on the same static payload which bootstraps and renders hash-specific files identically across all three.
+
+---
+
+## 1. `server`
+
+### Responsibilities:
+
+- **Execute unit tests at build time** 
+- **Static analysis of source files**
+- **Hash tree construction and cardinality computation**
+- **Inline and archive versioned part definitions into `/${version}.js`**
+- **Respond to HTTP requests**
+- **Render full HTML snapshots for any valid hash**
+- **Serve the archived script**
+
+### Features:
+
+- Resolves the entire application structure into a single build artifact
+- Serializes all parts into JavaScript literals
+- Sets default application state to be rendered server-side
+- Enables SEO by server-rendered HTML for any permalink
+- Outputs CSS-inlined, DOM-complete pages for fast first paint
+- Injects minimal bootstrap logic to register the service worker and transfer control to the client
+- Stateless; only computes a single frame of the app based on URL state
+- All logic is deterministic and derived from the hash tree
+
+---
+
+## 2. `worker`
+
+### Responsibilities:
+
+- **Controls all client-side network requests after installation**
+- **Hydrates the static DOM rendered by the server**
+
+### Features:
+
+- Ensures full offline support
+- Because all service workers are static and versioned, the app doesn't use network transactions
+- Manages asset caching and updates using browser-native SW APIs
+- Acts as the bridge between the server-rendered files and the client window
+
+---
+
+## 3. `client`
+
+### Responsibilities:
+
+- **Hydrates server renders and handles all DOM updates**
+- **Listens for user interaction events** such as clicks, keypresses, and pointer movements
+- **Reacts performantly to user input** by updating application state with minimal recomputation
+- **Interprets the full application state**
+
+### Features:
+
+- Presents the final local application
+- Manages user interaction, animations, and local rendering
+- Encodes new state changes back into the URL without needing a backend
+- Offers fast, smooth, and rich/stateful cross-origin navigation
+- Seamless rendering hand-off with no flash-of-unstyled-content (FOUC) on hydration.
+
+---
+
+## Shared Behavior Across Environments
+
+- **Immutable State Roots**: All environments operate on the same root hash model
+- **State Derivation**: Given a URL, all environments reconstruct the same system state
+- **Hydration Logic**: Service worker and client window bootstrap from the static state encoded in the URL
+
+---
+
+## Summary
+
+kireji achieves full-stack consistency by applying the same hash-based logic across three distinct environments. Each environment is stateless, reactive, and bound by a shared contract: the application's entire state must be fully described and derived from the URL alone. This approach eliminates backend dependency while enabling rich local state persistence and sharing, SEO, PWA functionality, real-time interaction and LTE version support.

package/docs/FUNDING.yml

@@ -0,0 +1,5 @@
+patreon: kireji
+ko_fi: kireji
+github: EJAugust
+thanks_dev: u/gh/ejaugust
+custom: ["https://www.paypal.me/kireji1"]

package/docs/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Eric Augustinowicz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/docs/README.md

@@ -0,0 +1,152 @@
+# kireji: Entropy-Perfect Multi-Origin Web Applications
+
+**kireji** is a web framework that maximally compresses data models using minimal perfect hash functions (MPHFs). It achieves the information-theoretic lower bound, creating the smallest possible collision-free, duplicate-free and gap-free hashes for arbitrary data.
+
+Any group of applications powered by kireji can have its entire group state stored in a tight place - like a single URL or even a DNS TXT record. Model data is recovered instantly from a hash and vice-versa. This gives applications deterministic, lossless deep linking, state bookmarking, historical replay and peer-to-peer sharing (via simple URL sharing) without users interacting with a central server.
+
+---
+
+## Entropy-Perfect Encoding
+
+Each application state is assigned a unique variable-length base64 hash, derived from a bijective minimal perfect hash function. This makes them as compact and expressive as is mathematically possible.
+
+kireji provides a compression solution that is uniquely built for the given data model and can represent every state in that model.
+
+All kireji hashes are inherently integers (implemented using the `bigint` primative in JavaScript). Because the hash function has no gaps, no duplicates, and no collisions, it is not possible to achieve a smaller lossless hash of a given data model than this.
+
+If there are 10,000,000,000,000,000,000,000,000,000,000,000,000,000,000 possible ways to populate your application's data model, then kireji produces a hash integer that is always between 0 and 9,999,999,999,999,999,999,999,999,999,999,999,999,999,999. kireji can then instantly hash any instance of the data model and instantly recover one from any integer in that range.
+
+An example use-case of this is embedding rich state information in places with limited space, such as a URL or DNS TXT record, without the syntactical overhead of query parameters,JSON objects, or delimiters.
+
+```
+https://www.ejaugust.com/0.126.3/4lb5kAsH_R0Dv_UHg/
+```
+
+## MVC + MPHF Architecture
+
+kireji can also be used as a compelete front-end framework. Its minimal perfect hash function is highly reactive with a built-in event system. It instantly reflects per-component tweaks to a given model with an extensible model-view-controller (MVC) archetecture.
+
+* Each controller is a stateful component (called a <strong>part</strong>) with its own cardinality.
+* Parts assemble like LEGO® bricks, with a root part producing a hash representing its entire hierarchy.
+* JavaScript's prototype chain enables compositional inheritance between parts.
+
+---
+
+## DNS-Based Namespacing
+
+When used as a web application front-end framework, each part in a kireji model can be assigned a name that follows DNS semantics so that a web application's URL (such as [www.ejaugust.com](https://www.ejaugust.com)) can be quickly discerned from a runtime reference to one of its parts, such as:
+
+```js
+_.app.kireji.www.editor.selected
+```
+
+The root part is represented by `_` and is the only global object. This prevents poluting the global namespace and allows all parts to make absolute reference to eachother.
+
+The framework stores its MVC abstracts and MPHF arithmetic under the domain name `"core.parts"`, allowing them to be reached like so:
+
+```js
+_.parts.core
+```
+
+You can explore this organization in action by going to [www.kireji.app](https://www.kireji.app).
+
+---
+
+## Live Applications
+
+kireji is in alpha. To see the technology in action, check on the kireji.app platform. This is a connected cross-origin app ecosystem that unites eight different web applications into a single state. That way, as users browse between applications, they applications have in-depth knowledge of eachother's state.
+
+This is done completely without cookies, javascript storage APIs, user authentication, or uploading state information to a central server. As a consequence, these applications provide a permalink to every possible state they can be in. This enables robust debugging.
+
+* [kireji.app](https://www.kireji.app) – an entropy and hash-space explorer for the platform
+* [ejaugust.com](https://www.ejaugust.com) – a notebook-style blog about the platform
+* [desktop.parts](https://www.desktop.parts) – a preview of a GUI-based OS experience
+### Coming Soon
+
+The following apps are not built yet, but their domain names and landing pages have been added to the platform:
+* [core.parts](https://www.core.parts) – likely to become a web-based Universal IDE
+* [user.parts](https://www.user.parts) – potential editor for software parts
+* [glowstick.click](https://www.glowstick.click) – purpose TBD
+* [kireji.io](https://www.kireji.io) – the future gamified UIDE
+* [orenjinari.com](https://www.orenjinari.com) – example of an artist's portfolio
+
+---
+
+## Learn More
+
+<!-- Looking ahead? See [FUTURE.md](FUTURE.md) for a deep dive into what's coming next.-->
+Explore the technical background and ideas that shape the kireji platform:
+
+* [Entropy-Perfect Encoding](https://www.ejaugust.com/0.126.4/4lb5kAh4PhZXOKxrM/) — on URL space, compression theory, and minimal perfect hash functions
+* [The Charm](https://www.ejaugust.com/0.126.3/4lbxJ29P-vnXOKxrM/) — on measuring entropy and URL information density
+* [Why DNS?](https://www.ejaugust.com/0.126.4/4lbHaxsKnzRXOKxrM/) — part namespacing and platform-wide coordination
+<!--
+* [The Multiverse and the Universal IDE](https://www.ejaugust.com/0.126.4/4lbeO3z_cmrXOKxrM/) — metaphors for self-rewriting environments
+* [The Gamified Universal IDE](https://www.ejaugust.com/0.126.4/4lbofySVBqVXOKxrM/) — an aspirational vision of immersive development tools -->
+
+---
+
+## **Technology Stack**
+
+* **JavaScript (ECMAScript)**
+* **CSS (Vanilla)**
+* **HTML (W3C Standards)**
+* **Service Workers for offline support**
+* **Serverless-compatible HTML rendering**
+
+---
+
+### **Zero Dependencies: A Simpler Equation**
+
+kireji is written entirely with vanilla JavaScript, CSS, and HTML. No libraries, frameworks, or third-party packages are imported.
+
+This choice was made to preserve full control over the performance of the hash function, align closely with web standards, reduce dependency resolution for applications using kireji, and to offer an opportunity to simplify the equation that defines the system's behavior.
+
+By encoding its own components within its data model, kireji and its surrounding data model can be reasoned about end-to-end, as a self-contained and self-descriptive system.
+
+---
+
+## **Current Status**
+[![Project Status: Alpha](https://img.shields.io/badge/Project%20Status-Alpha-orange)](https://www.repostatus.org/#alpha)
+[![Commits](https://img.shields.io/github/commit-activity/t/EJAugust/EJAugust)](https://github.com/EJAugust/EJAugust)
+[![GitHub Last Commit](https://img.shields.io/github/last-commit/EJAugust/EJAugust)](https://github.com/EJAugust/EJAugust)
+
+The following milestones completed:
+
+* Core framework functionality
+* CI/CD pipeline
+* MPFH for stateless deep linking and data compression
+* Reactive front-end framework via MVC + MPFH
+* Domain-named archetecture ready for DNS integration
+* In-platform part inspector
+* Node.js server built-in
+* Local debugging and development at localhost:3000
+* Desktop operating system preview
+* Ready-made stateful components with HTML and CSS, such as
+  - Scroller with custom scroll-bar implementation (more customizable than the native scrollbar)
+  - Color mode management that automatically computes shades from a given color pallete
+  - Additive parts for mutually exclusive variable assignments
+  - Multiplicative parts for independant variables
+  - Movie clip part for animating data models with a dedicated hash for every frame
+  - Notebook - a blog template
+
+### **Roadmap**
+
+| Phase                                    | Status      |
+| ---------------------------------------- | ----------- |
+| **Minimal Perfect Hashing For Any Data** | Completed   |
+| **Reacting MVC Framework**               | Completed   |
+| **CI/CD Pipeline**                       | Completed   |
+| **Model LTS and Versioning Strategy**    | Completed   |
+| **NPM Packages and Project Generation**  | In Progress |
+| **Debug Tools, Docs**                    | In Progress |
+| **Operating System Concept**             | In Progress |
+| **Transfinite State Space**              | Planned     |
+| **Advanced DNS Integration**             | Planned     |
+| **Integrated Development Environment**   | Planned     |
+
+---
+
+## **License and Attribution**
+
+<sub>© 2013–2025 Eric Augustinowicz and Kristina Soriano. All Rights Reserved.</sub> <sub>This is a personal research project in active development. It's not production-ready. Please do not copy or redistribute this codebase or its methods. All content is considered prior art.</sub>

package/docs/VERSIONING.md

@@ -0,0 +1,87 @@
+# kireji – Versioning and Long-Term Stability
+
+This document outlines the versioning strategy used by kireji to maintain consistency across application states and ensure long-term permalink stability.
+
+---
+
+## 1. Why Versioning Matters in kireji
+
+Unlike traditional applications that store state on the backend, kireji encodes all runtime state directly into the URL. This creates a permalink to any exact state but also a challenge: ensuring old links continue to work as the framework evolves.
+
+To solve this, kireji provides a **semantic versioning model** for its core hash function and handles archiving and importing single-file JavaScript files that represent previous versions of the application. These previous versions can be curated by simply removing or adding these JS artifacts into the archive.
+
+---
+
+## 2. Semantic Versioning Scheme
+
+The hash function that defines part behavior and layout is versioned using the standard **major.minor.patch** format:
+
+```
+MAJOR.MINOR.PATCH
+```
+
+| Level | When to Increment                                      |
+| ----- | ------------------------------------------------------ |
+| Major | Breaking change to existing state mappings             |
+| Minor | New routes added, existing links still work            |
+| Patch | Bugfixes, small adjustments, no impact on URL behavior |
+
+### Example:
+
+* `1.0.0`: First long-term stable version
+* `1.1.0`: Adds new application without changing old routes
+* `2.0.0`: Refactors match/mix behavior in a way that invalidates some previous URLs
+
+Until version `1.0.0`, kireji is in **alpha** and the hash tree may change without stability guarantees.
+
+---
+
+## 3. State Stability and Backward Compatibility
+
+Each version of the hash tree can be treated as its own schema for URL encoding and decoding. kireji sets aside a small reserved namespace for routing to a specific version of the tree.
+
+This allows developers to:
+
+* Pin content to a specific version
+* Maintain deep links in notes or docs
+* Add new routes or applications without breaking old ones
+
+Hashes can be translated across versions. This is achieved by allowing any previous version of the application to unpack a given hash into a serialized form that later versions can parse.
+
+---
+
+## 4. Archived Versions
+
+To preserve past behavior, all previously deployed versions of the hash tree are still available, archived and bundled according to their version number.
+
+This ensures that even if the project evolves rapidly, any link shared generated in a previous version of the application can still reconstruct its corresponding UI state.
+
+Archived versions include:
+
+* A frozen copy of the MPHF tree
+* Static copy of all content
+* Git metadata to link back to that version's commit
+
+---
+
+## 5. Planned Stability Milestone
+
+| Target Version | Purpose                                          |
+| -------------- | ------------------------------------------------ |
+| `1.0.0`        | First stable release with backward compatibility |
+| `1.x.x`        | Non-breaking extensions                          |
+| `2.0.0`        | First intentional breaking change                |
+
+Developers working with the alpha version 0.x.x should treat permalinks as non-durable while the deployment strategy matures.
+
+---
+
+## 6. Automatic Versioning
+
+kireji includes an **automatic versioning system** built into its local development environment. At build time, if the environment is detected as local, the framework allows the developer to specify change severity (major, minor, or patch) and the system automatically increments and outputs the appropriate next version number in the console at build time. This ensures consistent version tracking and LTE backwards compatibility testing during feature implementation.
+
+## Summary
+
+kireji treats the application state as a form of typed data and commits to preserving that data over time through semantic versioning. The versioning system ensures that every URL, once published, can remain a valid and functional entry point into the application—without requiring a database or server persistence.
+
+As the framework matures, this commitment to permalink durability will allow users and developers to build confidently on top of a stable foundation.

package/package.json

@@ -0,0 +1,69 @@
+{
+ "name": "kireji",
+ "version": "0.0.1",
+ "description": "A web framework for stateful, entropy-perfect, multi-origin web applications. Currently in alpha. Expect breaking changes for version 0. Use with caution!",
+ "type": "module",
+ "main": "./src/index.js",
+ "scripts": {
+  "test": "node test"
+ },
+ "repository": {
+  "type": "git",
+  "url": "git+https://github.com/kireji-app/kireji.git"
+ },
+ "keywords": [
+  "dns",
+  "framework",
+  "web",
+  "frontend",
+  "state-machine",
+  "static",
+  "operating-system",
+  "routing-engine",
+  "perfect-hash",
+  "compression-algorithm",
+  "perfect-hashing",
+  "automatic-versioning",
+  "permalink-engine",
+  "multi-origin",
+  "minimal-perfect-hash-function",
+  "minimal",
+  "perfect",
+  "hash",
+  "function",
+  "state",
+  "model",
+  "hashing",
+  "url",
+  "encoding",
+  "decoding",
+  "tuple",
+  "choice",
+  "sum-type",
+  "product-type",
+  "disjoint-union",
+  "cartesian-product",
+  "structured-data",
+  "url-state",
+  "algebraic-data-types",
+  "radix",
+  "bitpacking",
+  "bigint"
+ ],
+ "author": "Eric Augustinowicz",
+ "license": "MIT",
+ "bugs": {
+  "url": "https://github.com/kireji-app/kireji/issues"
+ },
+ "homepage": "https://github.com/kireji-app/kireji#readme",
+ "types": "./src/index.d.ts",
+ "exports": {
+  ".": {
+   "types": "./src/index.d.ts",
+   "default": "./src/index.js"
+  },
+  "./package.json": "./package.json",
+  "./LICENSE.md": "./docs/LICENSE.md",
+  "./README.md": "./docs/README.md"
+ }
+}

package/src/index.d.ts

@@ -0,0 +1,2 @@
+export declare class Kireji {
+}

package/src/index.js

@@ -0,0 +1,5 @@
+class Kireji {
+
+}
+
+export { Kireji }

package/test.js

@@ -0,0 +1,3 @@
+import { Kireji } from "./src/index.js"
+
+console.log("All zero tests passed.")