kireji 0.0.6 → 0.0.7

package/README.md

@@ -1,100 +1,68 @@
-> ### NOTE
-> This node package is currently an empty placeholder for a web framework under development.
->
-> Visit the working demo project [here](https://github.com/kireji-app/demo#readme).
->
-> Read this documentation to get an idea of the framework's intent and features.
->
-> Check back later to see if the package has been populated.
-
-# **kireji:**<br><sup><sub>Entropy-perfect web apps</sub></sup>
-kireji is a reactive full-stack web framework that uses minimal perfect hash functions (MPHFs) to achieve the information-theoretic lower bound of data compression.
-
-An MPFH is a collision-free, duplicate-free and gap-free hash function that provides a compression solution specialized for a given data model. It assigns a unique integer to every state in the model.
-
-Rich model data is recovered instantly from a hash and vice versa, with hashes compact enough to fit in URLs or DNS TXT records.
-
-Applications powered by kireji feature state-complete deep linking, enabling session bookmarking, peer-to-peer data sharing without a central server, and cross-origin communication via URL.
-
-## MVC + MPHF Architecture
-
-kireji integrates minimal perfect hash functions (MPHFs) with the model-view-controller (MVC) paradigm by using hashes as a canonical data model.
-
-* Each controller is a stateful component (called a <strong>part</strong>) with a dedicated hash function.
-* Parts assemble like LEGO® bricks, each assembly producing a new hash function derived from its subparts.
-* JavaScript's prototype chain powers compositional inheritance between parts.
-
-## DNS-Based Namespacing
-
-<h3><a href="https://www.ejaugust.com/0.131.3/4lbHaxsKnzRXOKxrM/"><img src="https://raw.githubusercontent.com/kireji-app/demo/refs/heads/main/src/com/ejaugust/note/part.png" style="width:1.25em" alt="part icon" />&nbsp;&nbsp;<sup>Why DNS?<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<sup>⟍&nbsp;</sup><sub>Further Reading</sub></sup></a></h3>
+# Kireji - *Web Framework*
+**Part of the Kireji Project**
+> *An application is the state it's in.*
+## Overview
+The Kireji Web Framework is a reactive full-stack web framework that uses the MPHF Coordinate System and the MVC paradigm to build multi-origin web app ecosystems. It offers a routing system that achieves the information-theoretic lower bound of data compression, enabling comprehensive deep linking, session bookmarking without user accounts or local storage, peer-to-peer data sharing without uploads or accounts, and cross-origin communication without cookies or CORS.
+## The Kireji Project
+The Kireji Project poses a question: **What if we could treat all functional software as points in a single, mathematically mapped, and traversable space?**
+| Repo | Purpose
+| ---- | -------
+| [MPHF](https://github.com/kireji-app/mphf#readme) | [Coordinate System<br><sub>Provides the bijective coordinate system</sub>](https://github.com/kireji-app/mphf#readme)
+| **Kireji** | **Web Framework - ★ You are here<br><sub>Uses MPHF to encode app state in URLs and manage cross-origin traversal</sub>**
+| [Demo](https://github.com/kireji-app/demo#readme) | [App Ecosystem<br><sub>Demonstrates practical applications of the Kireji Project</sub>](https://github.com/kireji-app/demo#readme)
+## Implementation
+
+> <sub>Note: This is currently an empty placeholder for the framework that powers the [Demo App Ecosystem](https://github.com/kireji-app/demo#readme). Check back later to see if the package has been populated.</sub>
+
+This framework uses the **MPHF Coordinate System** to assign a unique, gap-free coordinate to every valid point in a space constrained by its component definitions. It uses the **MVC paradigm** to efficiently update the DOM. It uses a **packing mechanism** to create single-artifact builds. It provides a library of **premade components** including a **web server** and **service worker** to bootstrap the development process.
+
+### Components
+Components act to refine the "Total Software Space" into a manageable set of **algebraically constrained, functional applications.**
+
+This refinement is designed to provide:
+- **Guaranteed Functionality:** Ensuring every coordinate represents a stable, working application (no "one sandal, one stiletto" combinations).
+- **Comprehensive Deep Linking:** Allowing every coordinate to be bookmarked and shared, retaining a full, multi-origin session state in the most compressed URL possible without reliance on cookies, servers, or user tracking.
+- **Component Encapsulation:** Defining all applications as assemblies of stateful components (called **parts**) built on the MPHF-MVC backbone. Parts then assemble like LEGO® bricks, each assembly representing its own configuration space.
+- **Reactive Navigation:** Ensuring navigation from one coordinate to another changes only the page elements that need to change to reflect the new position.
+
+### Namespacing
 
 Parts in kireji are assigned unique names following DNS semantics, relating a web application's origin (e.g., www.ejaugust.com) to its individual components, for example:
 
 ```js
-_.com.ejaugust
-_.com.ejaugust.scroller
-_.com.ejaugust.www
-_.com.ejaugust.www.home
-_.com.ejaugust.www.notes
+_.com.example
+_.com.example.scroller
+_.com.example.www.home
+_.com.example.www.blog
 ```
 
-The root part, represented by `_`, is the only global object. This allows parts to reference each other without polluting the global namespace.
-
-The framework provides a set of premade parts like MVC abstracts and MPHF arithmetic under the domain "core.parts":
+### Premade Components
+The framework provides MVC abstracts and MPHF arithmetic under the domain "core.parts":
 
 ```js
 _.parts.core.mix
 _.parts.core.match
 _.parts.core.clip
+...
 ```
 
-You can explore this organization in action by going to [www.kireji.app](https://www.kireji.app).
-
-## Made with Vanilla JS
-
-kireji does not import any third-party libraries, frameworks, or packages so that it can be reasoned about end-to-end as a self-contained and self-descriptive system.
-
-## Live Applications
-
-kireji is in alpha. To see the technology in action, check out the [demo](https://github.com/kireji-app/demo) repo.
-<!--
-## **Current Status**
-
-The following milestones completed:
+It provides bootstrapping and full-stack functionality under the domain "desktop.parts":
+```js
+_.parts.desktop.server
+_.parts.desktop.client
+_.parts.desktop.worker
+_.parts.desktop.addressBar
+...
+```
 
-* Core framework functionality
-* CI/CD pipeline
-* MPFH for stateless deep linking and data compression
-* Reactive front-end framework via MVC + MPFH
-* Domain-named architecture 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 palette
-  - Additive parts for mutually exclusive variable assignments
-  - Multiplicative parts for independent variables
-  - Movie clip part for animating data models with a dedicated hash for every frame
-  - Notebook - a blog template
+## Tech Stack
 
-### **Roadmap**
+The Kireji Web Framework does not import any third-party libraries, frameworks, or packages so that it can be reasoned about end-to-end as a self-contained and self-descriptive system.
 
-| 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     |
--->
 ## Status and License
+The Kireji Web Framework is in **Alpha**.\
+The Kireji Project is in **early research and development**.
+
 [![kireji on npm](https://img.shields.io/npm/v/kireji?style=for-the-badge&labelColor=CB3837&logo=npm&logoColor=white&label=NPM+package&color=212121)](https://www.npmjs.com/kireji)
 <br>[![Project Status: Alpha](https://img.shields.io/badge/status-alpha-212121?style=for-the-badge&labelColor=181717&logo=github&logoColor=white)](https://www.repostatus.org/#alpha)
 <br>[![Commits](https://img.shields.io/github/commit-activity/t/kireji-app/kireji?style=for-the-badge&labelColor=181717&color=212121&logo=github&logoColor=white)](https://github.com/kireji-app/demo/commits/)

package/package.json

@@ -1,6 +1,6 @@
 {
  "name": "kireji",
- "version": "0.0.6",
+ "version": "0.0.7",
  "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",

package/docs/ARCHITECTURE.md

@@ -1,90 +0,0 @@
-# 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

@@ -1,89 +0,0 @@
-# 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/VERSIONING.md

@@ -1,87 +0,0 @@
-# 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.