Initial Commit

Author: cybercussion

.github/workflows/deploy.yml

@@ -0,0 +1,45 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Inject Production Base Path
+        # Swaps the local development base tag for the production subdirectory
+        run: |
+          sed -i 's|<base.*>|<base href="/axiom/">|g' index.html
+          touch .nojekyll
+          cp index.html 404.html
+      
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          # Zero-build project: The root directory IS the artifact
+          path: '.'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -0,0 +1,26 @@
+# --- Axiom: System Junk ---
+.DS_Store
+Thumbs.db
+.cache/
+.tmp/
+*.log
+*.swp
+
+# --- Node & Dependencies ---
+# We use them for tools/dev, but they never touch the repo
+node_modules/
+package-lock.json
+npm-debug.log*
+
+# --- IDEs & Environments ---
+.vscode/
+.idea/
+.env
+.env.local
+
+# --- Build Output ---
+dist/
+
+# --- Project Specific ---
+# If your feature tool generates temp files
+tools/.temp/

README.md

@@ -0,0 +1,111 @@
+# Project Axiom
+
+> **"Nullius in verba"** (Take nobody's word for it) — Royal Society Motto
+
+Welcome to **Axiom**. We mistakenly decided that 500MB `node_modules` folders, 30-second builds, and debugging transpilation errors were "modern web development."
+
+We were wrong.
+
+Axiom is a **zero-build**, **zero-dependency**, **vanilla Web Standards** architecture. It runs directly in the browser. It respects your RAM. It respects your time.
+
+---
+
+## ⚡ The Architecture (TL;DR)
+
+### 1. The "State" (Reactivity)
+**File:** `src/core/state.js`
+It's not a global store library. It's a `Proxy`.
+- **Reactive:** You touch `state.data.count`, the UI updates. Magic.
+- **Optimistic:** `state.mutate()` updates the UI *instantly*. If the server hiccups, it rolls back automatically. We assume success because we're optimists.
+- **Smart Queries:** `state.query()` handles the boring stuff (fetching, loading states, error handling, caching) so you don't have to.
+
+### 2. The "Router" (Navigation)
+**File:** `src/core/router.js`
+It's roughly 200 lines of code. Popular alternatives are 30,000. existentially weigh those options.
+- **Parallel Loading:** It fetches your JS module AND your data simultaneously. No waterfalls here.
+- **Panic Mode:** If the route fails, we show a 404. If the 404 fails, we panic gracefully to avoid the White Screen of Death.
+- **View Transitions:** Native browser animations on navigation. Smoother than butter.
+
+### 3. The "Gateway" (API)
+**File:** `src/core/gateway.js`
+A wrapper around `fetch` that actually has a brain.
+- **Content-Type Agnostic:** JSON? Text? Blob? It figures it out.
+- **Unified Headers:** Handles your auth tokens and version stamping automatically.
+
+### 4. The "Components" (UI)
+**File:** `src/shared/base-component.js`
+Web Components. Native Shadow DOM.
+- **Surgical Updates:** We don't re-render the whole world. We find the node, we change the text. Fast.
+- **Theme Injection:** Adopts global styles automatically. No css-in-js libraries required.
+
+---
+
+## 🚀 Quick Start
+
+You don't need `npm install`. You don't need `npm run build`.
+
+1. **Get the code:**
+   ```bash
+   git clone https://gitlab.com/cybercussion/axiom.git
+   ```
+
+2. **Serve it:**
+   (Browsers block ES Modules on `file://` protocol because security).
+   (We use Vite or a SPA-aware server to ensure routing works correctly).
+   ```bash
+   npm install
+   npm run dev
+   ```
+
+3. **Open it:**
+   `http://localhost:3000`
+
+That's it. You're developing.
+
+---
+
+## 🛠 Feature Generator
+
+If you're lazy (and you should be), use the generator to make new distinct features.
+
+```bash
+# Creates src/features/profile/profile.js, .css, etc.
+npm run feature profile
+```
+
+## 🔍 SEO & PWA Injection
+
+Don't hand-write 40 lines of `<meta>` tags like a caveman. We have a wizard for that.
+
+```bash
+# Interactive Wizard (Title, Desc, Social Images)
+node tools/create-seo.js
+
+# Turn it into an installable PWA (Manifest generation)
+node tools/create-seo.js --pwa
+```
+
+
+## 📦 Production Build
+
+**"Wait, you said no build step?"**
+Correct. You don't *need* it. But if you want to crush your assets into a fine powder for production:
+
+```bash
+# Minifies JS (Terser) & CSS (CSSO) -> /dist
+npm run build
+```
+
+This is **non-destructive**. It reads your source and writes to `dist/`.
+
+---
+
+## 📝 Philosophy
+
+**If the platform can do it, use the platform.**
+
+- **Variables:** CSS Custom Properties. Not SASS Variables.
+- **Modules:** ES Modules (ESM). Not CommonJS require().
+- **State:** JS Proxy. Not a specialized reduced store library.
+
+Enjoy your retrieved sanity.

docs/graphql-readme.md

@@ -0,0 +1,95 @@
+# GraphQL in Axiom
+
+So you want to use GraphQL.
+
+**STOP.** Put down `apollo-client`. Step away from `urql`.
+
+You do not need a 40kb library to send a POST request string.
+
+## The Axiom Way
+
+GraphQL is just HTTP POST with a specific body shape. Our `gateway.js` can handle this natively with zero dependencies.
+
+### 1. The Wrapper
+
+You can create a specialized `graphql` helper, or extend the gateway. Here is the "vanilla" implementation:
+
+```javascript
+// src/core/graphql.js
+import { gateway } from './gateway.js';
+
+export const gql = (query, variables = {}) => {
+  return gateway.request('/graphql', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ query, variables })
+  }).then(res => {
+    if (res.errors) throw res.errors; // GraphQL-level errors
+    return res.data;
+  });
+};
+```
+
+### 2. State Integration
+
+Axiom's `state.js` doesn't care if data comes from REST or GraphQL. Use `state.query` exactly the same way.
+
+```javascript
+// src/features/profile/profile.js
+import { state } from '@state';
+import { gql } from '@core/graphql';
+
+const GET_PROFILE = `
+  query GetProfile($id: ID!) {
+    user(id: $id) {
+      name
+      avatar
+      role
+    }
+  }
+`;
+
+// In your component
+connectedCallback() {
+  state.query('current-user', () => gql(GET_PROFILE, { id: '123' }));
+  
+  this.subscribe('current-user', (user) => {
+    this.render(user);
+  });
+}
+```
+
+### 3. Mutations (Optimistic)
+
+GraphQL mutations work perfectly with `state.mutate` for optimistic UI updates.
+
+```javascript
+const UPDATE_AVATAR = `
+  mutation UpdateAvatar($url: String!) {
+    updateAvatar(url: $url) {
+      url
+    }
+  }
+`;
+
+function onAvatarUpload(newUrl) {
+  state.mutate('current-user', (current) => {
+    // 1. Optimistic Update
+    // Return the shape you EXPECT the server to return, or the new state
+    return { ...current, avatar: newUrl };
+  }, async () => {
+    // 2. The Real Network Request
+    return gql(UPDATE_AVATAR, { url: newUrl });
+  });
+}
+```
+
+## Summary
+
+1.  **Define Queries as Strings**: Template literals are fine.
+2.  **Use `state.query`**: It handles caching, loading states, and deduplication for you.
+3.  **Use `state.mutate`**: It handles optimistic rollbacks automatically.
+
+Zero build steps. Zero extra bundles. Pure performance.

docs/realtime-readme.md

@@ -0,0 +1,76 @@
+# Real-Time in Axiom (WebSockets)
+
+Most frameworks require "Middlewares", "Thunks", or "Sagas" to handle WebSockets.
+Axiom requires... **Basic Javascript.**
+
+Because our `state` is a Proxy, you can write to it from *anywhere*. Even a WebSocket callback.
+
+## The Pattern
+
+We treat the WebSocket as just another source of truth.
+
+```javascript
+// src/core/socket.js
+import { state } from '@state';
+
+let socket;
+
+export function connect() {
+  socket = new WebSocket('wss://api.axiom.com/v1/stream');
+
+  socket.onmessage = (event) => {
+    const { type, payload } = JSON.parse(event.data);
+
+    // MIND BENDING PART:
+    // We just... write to the state.
+    // The UI updates automatically.
+    
+    if (type === 'STOCK_UPDATE') {
+       // If you have a list, find and update
+       const index = state.data.stocks.findIndex(s => s.id === payload.id);
+       if (index !== -1) {
+         state.data.stocks[index] = payload; 
+       }
+    }
+    
+    if (type === 'CHAT_MESSAGE') {
+       // Append to array
+       state.data.messages = [...state.data.messages, payload];
+    }
+  };
+}
+```
+
+## Usage in Components
+
+Your components don't even need to know WebSockets exist. They just subscribe to the data.
+
+```javascript
+// src/features/ticker/ticker.js
+import { BaseComponent } from '@shared/base-component.js';
+
+class StockTicker extends BaseComponent {
+  connectedCallback() {
+    // This component updates whenever 'stocks' changes.
+    // It doesn't care if it came from REST, GraphQL, or a Socket.
+    this.subscribe('stocks', (stocks) => {
+      this.render(stocks);
+    });
+  }
+}
+```
+
+## Why this is "Mind Bending"
+
+In Redux/Context, you'd need:
+1.  Socket Listener
+2.  Dispatch Action
+3.  Reducer Case
+4.  Selector
+5.  Component Re-render
+
+In Axiom:
+1.  Socket Listener writes to `state.data`.
+2.  Component updates.
+
+**Nullius in verba.**