atmx-web 0.42.0

package/justfile

@@ -0,0 +1,8 @@
+default:
+    @just --list
+
+build:
+    npm run build
+
+upload:
+    ./scripts/upload.sh

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "atmx-web",
+  "version": "0.42.0",
+  "description": "Axiom ATMX Core Runtime for Vanilla Web",
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "main": "./dist/atmx.umd.js",
+  "module": "./dist/atmx.es.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview"
+  },
+  "devDependencies": {
+    "tslib": "^2.8.1",
+    "typescript": "^5.9.3",
+    "vite": "^8.0.0"
+  }
+}

package/public/.axiom

@@ -0,0 +1,170 @@
+{
+    "endpoints": [
+        {
+            "cache_policy": {
+                "strategy": "stale_while_revalidate",
+                "ttlSeconds": 10
+            },
+            "id": 0,
+            "method": "GET",
+            "name": "get_user",
+            "path": "/users/{user_id}",
+            "retry_policy": {
+                "backoff": {
+                    "initialDelay": "500ms",
+                    "maxDelay": "30s",
+                    "multiplier": 2,
+                    "type": "exponential",
+                    "useJitter": true
+                },
+                "maxAttempts": 5,
+                "retryOnCodes": [
+                    502,
+                    503,
+                    504
+                ],
+                "retryOnTimeout": true
+            },
+            "return_type": {
+                "kind": "named",
+                "value": "User"
+            },
+            "validation_enabled": true
+        },
+        {
+            "cache_policy": null,
+            "id": 1,
+            "method": "POST",
+            "name": "create_user",
+            "path": "/users",
+            "retry_policy": null,
+            "return_type": {
+                "kind": "named",
+                "value": "User"
+            },
+            "validation_enabled": true
+        }
+    ],
+    "header": {
+        "axiom_version": "1.0",
+        "min_runtime_version": 1
+    },
+    "ir": {
+        "endpoints": [
+            {
+                "doc": null,
+                "id": 0,
+                "isStream": false,
+                "method": "GET",
+                "name": "get_user",
+                "parameters": [
+                    {
+                        "isOptional": false,
+                        "name": "user_id",
+                        "source": "path",
+                        "typeRef": {
+                            "kind": "int64"
+                        }
+                    }
+                ],
+                "path": "/users/{user_id}",
+                "returnIsOptional": false,
+                "returnType": {
+                    "kind": "named",
+                    "value": "User"
+                }
+            },
+            {
+                "doc": null,
+                "id": 1,
+                "isStream": false,
+                "method": "POST",
+                "name": "create_user",
+                "parameters": [
+                    {
+                        "isOptional": false,
+                        "name": "user",
+                        "source": "body",
+                        "typeRef": {
+                            "kind": "named",
+                            "value": "User"
+                        }
+                    }
+                ],
+                "path": "/users",
+                "returnIsOptional": false,
+                "returnType": {
+                    "kind": "named",
+                    "value": "User"
+                }
+            }
+        ],
+        "enums": {
+            "UserRole": {
+                "doc": null,
+                "name": "UserRole",
+                "values": [
+                    "admin",
+                    "user"
+                ]
+            }
+        },
+        "models": {
+            "User": {
+                "doc": "Usage docs: https://docs.pydantic.dev/2.10/concepts/models/\n\nA base class for creating Pydantic models.\n\nAttributes:\n    __class_vars__: The names of the class variables defined on the model.\n    __private_attributes__: Metadata about the private attributes of the model.\n    __signature__: The synthesized `__init__` [`Signature`][inspect.Signature] of the model.\n\n    __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.\n    __pydantic_core_schema__: The core schema of the model.\n    __pydantic_custom_init__: Whether the model has a custom `__init__` function.\n    __pydantic_decorators__: Metadata containing the decorators defined on the model.\n        This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1.\n    __pydantic_generic_metadata__: Metadata for generic models; contains data used for a similar purpose to\n        __args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these.\n    __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.\n    __pydantic_post_init__: The name of the post-init method for the model, if defined.\n    __pydantic_root_model__: Whether the model is a [`RootModel`][pydantic.root_model.RootModel].\n    __pydantic_serializer__: The `pydantic-core` `SchemaSerializer` used to dump instances of the model.\n    __pydantic_validator__: The `pydantic-core` `SchemaValidator` used to validate instances of the model.\n\n    __pydantic_fields__: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects.\n    __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects.\n\n    __pydantic_extra__: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra]\n        is set to `'allow'`.\n    __pydantic_fields_set__: The names of fields explicitly set during instantiation.\n    __pydantic_private__: Values of private attributes set on the model instance.",
+                "fields": [
+                    {
+                        "doc": null,
+                        "isOptional": false,
+                        "name": "id",
+                        "typeRef": {
+                            "kind": "int64"
+                        }
+                    },
+                    {
+                        "doc": null,
+                        "isOptional": false,
+                        "name": "name",
+                        "typeRef": {
+                            "kind": "string"
+                        }
+                    },
+                    {
+                        "doc": null,
+                        "isOptional": true,
+                        "name": "role",
+                        "typeRef": {
+                            "kind": "named",
+                            "value": "UserRole"
+                        }
+                    },
+                    {
+                        "doc": null,
+                        "isOptional": false,
+                        "name": "email",
+                        "typeRef": {
+                            "kind": "string"
+                        }
+                    }
+                ],
+                "name": "User"
+            }
+        },
+        "offlineConfig": null,
+        "serviceName": "app",
+        "specVersion": "1.0.0",
+        "target": null
+    },
+    "policies": null,
+    "project": {
+        "codec": "json",
+        "project_id": "python-example",
+        "schema_hash": "19b9c116af317a4e13b1a241d59088829d9af453a1a7bcb37054ab7184dc5381",
+        "variant": "default",
+        "version": "v0.1.4"
+    },
+    "schema_fbs": null,
+    "validators": {
+        "User": "properties:\n  email:\n    email: true\n    type: string\n  role:\n    options:\n    - type: enum\n      values:\n      - admin\n      - user\n    type: union\ntype: object\n"
+    }
+}

package/scripts/upload.sh

@@ -0,0 +1,61 @@
+#!/bin/bash
+set -e
+
+# 1. Load credentials from .env
+if [ -f .env ]; then
+  set -a
+  source .env
+  set +a
+else
+  echo "❌ Error: .env file not found."
+  exit 1
+fi
+
+if [ -z "$CLOUDFLARE_ACCOUNT_ID" ] || [ -z "$AWS_ACCESS_KEY_ID" ] || [ -z "$AWS_SECRET_ACCESS_KEY" ]; then
+  echo "❌ Error: Missing credentials in .env file."
+  exit 1
+fi
+
+# 2. Setup Variables
+BUCKET_NAME="atmx"
+ENDPOINT="https://${CLOUDFLARE_ACCOUNT_ID}.r2.cloudflarestorage.com"
+DIST_DIR="./dist"
+
+# Grab the version directly from package.json (e.g., "0.1.0")
+VERSION=$(node -p "require('./package.json').version")
+
+# We will upload to a versioned folder (v0.1.0) AND a "latest" folder
+FOLDERS=("v$VERSION" "latest")
+
+echo "🚀 Starting Upload for ATMX v$VERSION to Cloudflare R2..."
+
+# 3. Upload loop
+for FOLDER in "${FOLDERS[@]}"; do
+    echo "📁 Uploading to /$FOLDER/..."
+
+    # Upload UMD JS (for <script> tags)
+    aws s3 cp "$DIST_DIR/atmx.umd.js" "s3://$BUCKET_NAME/$FOLDER/atmx.umd.js" \
+        --endpoint-url "$ENDPOINT" \
+        --content-type "application/javascript" \
+        --cache-control "max-age=3600" \
+        --no-progress
+
+    # Upload ES JS (for ES module imports)
+    aws s3 cp "$DIST_DIR/atmx.es.js" "s3://$BUCKET_NAME/$FOLDER/atmx.es.js" \
+        --endpoint-url "$ENDPOINT" \
+        --content-type "application/javascript" \
+        --cache-control "max-age=3600" \
+        --no-progress
+
+    # Upload WASM (CRITICAL: Sets the application/wasm content-type)
+    aws s3 cp "$DIST_DIR/axiom_runtime.wasm" "s3://$BUCKET_NAME/$FOLDER/axiom_runtime.wasm" \
+        --endpoint-url "$ENDPOINT" \
+        --content-type "application/wasm" \
+        --cache-control "max-age=3600" \
+        --no-progress
+done
+
+echo "✅ Upload Complete!"
+echo "🌐 Your files are now available at:"
+echo "   - https://atmx.axiomcore.dev/v$VERSION/atmx.umd.js"
+echo "   - https://atmx.axiomcore.dev/latest/atmx.umd.js"

package/src/core/callback.ts

@@ -0,0 +1,92 @@
+// FILE: src/core/callback.ts
+import { EventType, AxiomError, AxiomResponse } from './types';
+
+// Store the active requests. We need to store a config object now, not just a callback function.
+export const pendingRequests = new Map<number, {
+    isStream: boolean,
+    onResponse: (res: AxiomResponse) => void,
+    onComplete: () => void
+}>();
+
+export function setupWebCallback(wasm: any) {
+    (window as any).axiom_web_callback = (
+        reqId: number, eventType: number, errorCode: number,
+        dataPtr: number, dataLen: number, errPtr: number, errLen: number
+    ) => {
+        const handler = pendingRequests.get(reqId);
+        if (!handler) {
+            // Memory must be freed even if JS abandoned the request!
+            if (dataPtr) wasm.axiom_free_memory(dataPtr, dataLen);
+            if (errPtr) wasm.axiom_free_memory(errPtr, errLen);
+            return;
+        }
+
+        let dataBytes: Uint8Array | null = null;
+        let errorJson: string | null = null;
+
+        // 1. Read Payload Memory
+        if (dataPtr !== 0 && dataLen > 0) {
+            const memory = new Uint8Array(wasm.memory.buffer);
+            dataBytes = new Uint8Array(memory.subarray(dataPtr, dataPtr + dataLen));
+            wasm.axiom_free_memory(dataPtr, dataLen);
+        }
+
+        // 2. Read Error Memory
+        if (errPtr !== 0 && errLen > 0) {
+            const memory = new Uint8Array(wasm.memory.buffer);
+            const errBytes = new Uint8Array(memory.subarray(errPtr, errPtr + errLen));
+            errorJson = new TextDecoder().decode(errBytes);
+            wasm.axiom_free_memory(errPtr, errLen);
+        }
+
+        // 3. Handle Completion Signal
+        if (eventType === EventType.Complete) {
+            handler.onComplete();
+            pendingRequests.delete(reqId);
+            return;
+        }
+
+        // 4. Handle Errors
+        if (eventType === EventType.Error) {
+            let richError: AxiomError;
+            if (errorJson) {
+                try { richError = JSON.parse(errorJson); }
+                catch (e) { richError = { stage: 'ffiBoundary', category: 'runtime', code: 'JsonParseFailure', message: `Parse failed: ${e}`, retryable: false }; }
+            } else {
+                richError = { stage: 'runtime', category: 'unknown', code: errorCode.toString(), message: 'Internal Wasm error', retryable: false };
+            }
+
+            handler.onResponse({ eventType, error: richError });
+
+            // Clean up the request on a fatal error
+            handler.onComplete();
+            pendingRequests.delete(reqId);
+            return;
+        }
+
+        // 5. Handle Data (Success, Cache, or Stream Chunk)
+        if (dataBytes) {
+            try {
+                const jsonString = new TextDecoder().decode(dataBytes);
+                const jsonData = JSON.parse(jsonString);
+
+                // Pass the data up to the Reactive Engine
+                handler.onResponse({
+                    eventType,
+                    data: jsonData,
+                    isFetching: eventType === EventType.CacheHitAndFetching,
+                    isStreamChunk: handler.isStream
+                });
+
+                // If it's NOT a stream, a NetworkSuccess means the request is fully complete.
+                if (!handler.isStream && eventType === EventType.NetworkSuccess) {
+                    handler.onComplete();
+                    pendingRequests.delete(reqId);
+                }
+
+            } catch (e) {
+                console.error("ATMX: Failed to parse JSON response from Axiom", e);
+            }
+        }
+    };
+}

package/src/core/context.ts

@@ -0,0 +1,56 @@
+// FILE: src/core/context.ts
+import { renderContext } from '../resolver/render';
+
+export type AtmxState = 'idle' | 'loading' | 'mutating' | 'data' | 'success' | 'error';
+
+export interface AtmxContextData {
+    state: AtmxState;
+    isFetching: boolean;
+    isMutating: boolean;
+    source: 'cache' | 'network' | null;
+    data: any;
+    error: any;
+}
+
+const contextRegistry = new WeakMap<HTMLElement, AtmxContextData>();
+
+export function getContext(element: HTMLElement): AtmxContextData {
+    if (!contextRegistry.has(element)) {
+        contextRegistry.set(element, {
+            state: 'idle', isFetching: false, isMutating: false,
+            source: null, data: null, error: null
+        });
+    }
+    return contextRegistry.get(element)!;
+}
+
+/**
+ * NEW: Recursively finds the nearest parent context that has actual data.
+ * This allows nested buttons to access $data from their parent queries.
+ */
+export function getClosestData(element: HTMLElement): any {
+    let current: HTMLElement | null = element.parentElement;
+    while (current) {
+        if (current.hasAttribute('ax-query') || current.hasAttribute('ax-mutate')) {
+            const ctx = contextRegistry.get(current);
+            if (ctx && ctx.data) return ctx.data;
+        }
+        current = current.parentElement;
+    }
+    return {}; // Return empty object if no parent data found
+}
+
+export function updateContext(element: HTMLElement, updates: Partial<AtmxContextData>) {
+    const current = getContext(element);
+    Object.assign(current, updates);
+
+    if (updates.state === 'loading') current.isFetching = true;
+    if (updates.state === 'mutating') current.isMutating = true;
+    if (updates.state === 'success' || (updates.state === 'data' && updates.isFetching === false)) {
+        current.isFetching = false;
+        current.isMutating = false;
+    }
+
+    contextRegistry.set(element, current);
+    renderContext(element, current);
+}

package/src/core/query.ts

@@ -0,0 +1,162 @@
+// FILE: src/core/query.ts
+import { wasmEngine, allocString, allocBytes } from "./wasm";
+import { pendingRequests } from "./callback";
+import { Route, buildRequestPath } from "./router";
+import { AtmxContextData } from "./context";
+import { EventType } from "./types";
+import { atmx } from "../index";
+
+let globalReqCounter = 0;
+type Listener = (state: Partial<AtmxContextData>) => void;
+
+export class ActiveQuery {
+  key: string;
+  route: Route;
+  args: Record<string, any>;
+  state: Partial<AtmxContextData>;
+  listeners: Set<Listener> = new Set();
+  currentReqId: number | null = null;
+
+  constructor(key: string, route: Route, args: Record<string, any>) {
+    this.key = key;
+    this.route = route;
+    this.args = args;
+    this.state = {
+      state: "idle",
+      isFetching: false,
+      source: null,
+      data: null,
+      error: null,
+    };
+  }
+
+  subscribe(listener: Listener) {
+    this.listeners.add(listener);
+    listener(this.state); // Instantly hydrate the DOM element with current state
+  }
+
+  update(newState: Partial<AtmxContextData>) {
+    this.state = { ...this.state, ...newState };
+    this.listeners.forEach((l) => l(this.state)); // Broadcast to all DOM elements!
+  }
+
+  fetch(force: boolean = false) {
+    if (this.state.isFetching && !force) return;
+
+    this.update({
+      state: this.state.data ? "data" : "loading",
+      isFetching: true,
+      error: null,
+    });
+
+    const reqId = ++globalReqCounter;
+    this.currentReqId = reqId;
+
+    const { path, remainingArgs } = buildRequestPath(this.route, this.args);
+
+    let payloadBytes = new Uint8Array(0);
+    if (Object.keys(remainingArgs).length > 0) {
+      payloadBytes = new TextEncoder().encode(JSON.stringify(remainingArgs));
+    }
+
+    if (atmx.debug) {
+      console.groupCollapsed(
+        `%c➔ WASM QUERY [#${reqId}]`,
+        `color: #7c3aed; font-weight: bold;`,
+      );
+      console.log("Namespace:", this.route.namespace);
+      console.log("Endpoint ID:", this.route.id);
+      console.log("Path:", path);
+      console.groupEnd();
+    }
+
+    pendingRequests.set(reqId, {
+      isStream: this.route.isStream,
+      onResponse: (res) => {
+        if (this.currentReqId !== reqId) return;
+
+        if (atmx.debug) {
+          const evtName =
+            res.eventType === 1
+              ? "NetworkSuccess"
+              : res.eventType === 2
+                ? "CacheHit"
+                : res.eventType === 3
+                  ? "CacheHitAndFetching"
+                  : res.eventType === 4
+                    ? "Error"
+                    : "Complete";
+          console.groupCollapsed(
+            `%c← WASM RESP [#${reqId}]`,
+            `color: #059669; font-weight: bold;`,
+          );
+          console.log("Event Type:", evtName);
+          if (res.data) console.log("Data:", res.data);
+          if (res.error) console.log("Error:", res.error);
+          console.groupEnd();
+        }
+
+        if (res.eventType === EventType.Error) {
+          this.update({ state: "error", error: res.error, isFetching: false });
+          return;
+        }
+
+        if (res.data) {
+          let source: "cache" | "network" = "network";
+          let isFetching = false;
+
+          if (res.eventType === EventType.CacheHit) {
+            source = "cache";
+            isFetching = false;
+          } else if (res.eventType === EventType.CacheHitAndFetching) {
+            source = "cache";
+            isFetching = true;
+          } else if (res.eventType === EventType.NetworkSuccess) {
+            source = "network";
+            isFetching = false;
+          }
+
+          this.update({ state: "data", data: res.data, source, isFetching });
+        }
+      },
+      onComplete: () => {
+        if (this.currentReqId !== reqId) return;
+        if (atmx.debug)
+          console.log(`%c✔ Stream Complete [#${reqId}]`, "color: #94a3b8;");
+        this.update({ isFetching: false });
+      },
+    });
+
+    const nsStr = allocString(this.route.namespace);
+    const mStr = allocString(this.route.method);
+    const pStr = allocString(path);
+    const payloadPtr = allocBytes(payloadBytes);
+    const tpStr = allocString(""); // Traceparent (empty for now)
+    const hStr = allocString(""); // Headers (empty for now)
+
+    wasmEngine.axiom_wasm_call(
+      reqId,
+      nsStr.ptr,
+      nsStr.len,
+      this.route.id,
+      mStr.ptr,
+      mStr.len,
+      pStr.ptr,
+      pStr.len,
+      tpStr.ptr,
+      tpStr.len,
+      hStr.ptr,
+      hStr.len,
+      payloadPtr,
+      payloadBytes.length,
+    );
+
+    wasmEngine.axiom_free_memory(nsStr.ptr, nsStr.len);
+    wasmEngine.axiom_free_memory(mStr.ptr, mStr.len);
+    wasmEngine.axiom_free_memory(pStr.ptr, pStr.len);
+    wasmEngine.axiom_free_memory(tpStr.ptr, tpStr.len);
+    wasmEngine.axiom_free_memory(hStr.ptr, hStr.len);
+  }
+}
+
+export const queryRegistry = new Map<string, ActiveQuery>();

package/src/core/router.ts

@@ -0,0 +1,91 @@
+// FILE: src/core/router.ts
+
+export interface RouteAuth {
+  required: boolean;
+  methods: any[];
+}
+
+export interface Route {
+  id: number;
+  namespace: string;
+  name: string;
+  method: string;
+  pathTemplate: string;
+  isStream: boolean;
+  auth?: RouteAuth | null;
+  bodyParam?: string | null; // <-- NEW
+}
+
+const routes = new Map<string, Route>();
+
+export function initRouter(namespace: string, contractJson: any) {
+  const endpoints = contractJson?.ir?.endpoints;
+  if (!endpoints) return;
+
+  const epList = Array.isArray(endpoints)
+    ? endpoints
+    : Object.values(endpoints);
+
+  epList.forEach((ep: any) => {
+    const routeKey = `${namespace}.${ep.name}`;
+
+    // ✨ Detect which param belongs in the body
+    const bodyParam =
+      ep.parameters?.find((p: any) => p.source === "body")?.name || null;
+
+    routes.set(routeKey, {
+      id: ep.id,
+      namespace: namespace,
+      name: ep.name,
+      method: ep.method ? ep.method.toUpperCase() : "GET",
+      pathTemplate: ep.path,
+      isStream: ep.isStream || false,
+      auth: ep.auth || null,
+      bodyParam: bodyParam, // <-- NEW
+    });
+  });
+  console.log(
+    `🛣️ ATMX Router: Mapped ${epList.length} endpoints for '${namespace}'.`,
+  );
+}
+
+export function resolveRoute(rpcCall: string): Route | null {
+  return routes.get(rpcCall.trim()) || null;
+}
+
+export function buildRequestPath(
+  route: Route,
+  args: Record<string, any>,
+): { path: string; remainingArgs: Record<string, any> } {
+  let finalPath = route.pathTemplate;
+  const remainingArgs = { ...args };
+
+  const pathMatches = finalPath.match(/\{([^}]+)\}/g);
+  if (pathMatches) {
+    pathMatches.forEach((match) => {
+      const key = match.replace(/[{}]/g, "");
+      if (remainingArgs[key] !== undefined) {
+        finalPath = finalPath.replace(
+          match,
+          encodeURIComponent(String(remainingArgs[key])),
+        );
+        delete remainingArgs[key];
+      }
+    });
+  }
+
+  if (route.method === "GET" && Object.keys(remainingArgs).length > 0) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(remainingArgs)) {
+      if (value !== undefined && value !== null) {
+        params.append(key, String(value));
+      }
+    }
+    const separator = finalPath.includes("?") ? "&" : "?";
+    finalPath += `${separator}${params.toString()}`;
+
+    for (const key of Object.keys(remainingArgs)) delete remainingArgs[key];
+  }
+
+  return { path: finalPath, remainingArgs };
+}