@vireocodedev/infrastructure 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vireocodedev
+
+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/README.md

@@ -0,0 +1,78 @@
+# @vireocodedev/infrastructure
+
+React-free browser infrastructure primitives for validated HTTP transport, connectivity, persistent state, session-expiry coordination, and execution-mode-aware services.
+
+The package owns reusable mechanisms. Applications still own configured transports, endpoint vocabulary, authentication and routing, heartbeat adapters, persistence services, query caching, service-worker lifecycle, and product UI.
+
+## Install
+
+```bash
+npm install @vireocodedev/infrastructure axios zod @preact/signals-core
+```
+
+The package is published publicly on npm; installation requires no registry
+authentication. TypeScript declarations are verified from the packed artifact
+with TypeScript 6, `moduleResolution: "Bundler"`, and `skipLibCheck: false`.
+Relative source maps with embedded source content are published intentionally
+for debugging.
+
+The package has no React, MUI, React Query, locale, or application singleton dependency.
+
+React adapters live in Starter UI:
+
+```ts
+import { useVireoOnlineStatus } from "@vireocodedev/ui";
+import { createVireoPagedSearchQueries } from "@vireocodedev/ui/tanstack-query";
+```
+
+## Public architecture
+
+```text
+application runtime and policy
+  -> createConnectivityState / getAppOnlineStatus
+  -> createModeAwareApi
+  -> AxiosHttpClient or postPagedSearch
+  -> Zod-validated response data
+  -> application cache and product state
+
+application storage -> createPersistentSignal
+application authentication -> createSessionExpiryChannel
+```
+
+All stateful factories are instance-scoped. Importing the package creates no query client, listeners, timers, session state, or storage state.
+
+## Mode-aware services
+
+`createModeAwareApi` composes online and offline service modules behind one application API. The application injects the current mode, guards, fallback classification, timing, and diagnostics policy. `transactional` can mark offline methods whose writes should prefer the online implementation while connectivity exists.
+
+## HTTP and pagination
+
+`AxiosHttpClient` centralizes injected Axios transport and Zod response validation. `postPagedSearch` validates the complete pageable envelope, not only its rows. Malformed filter JSON and invalid metadata fail closed.
+
+`sanitizeAxiosError` produces a deliberately small diagnostic object and never exposes request bodies, headers, query strings, or response data.
+
+## Connectivity
+
+`getAppOnlineStatus` and `subscribeToAppNetworkStatus` expose the browser's lightweight network hint. `createConnectivityState` combines that hint with optional heartbeat freshness and explicit backend availability. Runtime adapters own browser subscriptions and scheduling; the state factory enforces one active runtime owner.
+
+## Persistent state
+
+`createPersistentSignal` mirrors one typed storage key into a Preact core signal. Persistence occurs before the in-memory signal changes, so a failed write cannot leave the two representations inconsistent.
+
+## Session expiry
+
+`createSessionExpiryChannel` creates an isolated coordination channel. It deduplicates expiry notifications, suppresses them during intentional logout, and lets applications decide how listeners affect routing or authentication.
+
+## Failure semantics
+
+- Invalid HTTP data raises the original Zod error without logging raw payloads.
+- Malformed query filters fail before a request is sent.
+- Invalid pageable metadata is rejected at the API boundary.
+- Request cancellation is recognized without assuming DOM globals exist.
+- Connectivity policy and concurrent runtime ownership fail synchronously.
+- Persistence failures leave the signal unchanged.
+- Session listeners are isolated and may report failures through injected policy.
+
+## Verification and live documentation
+
+Package tests cover public services, transport boundaries, connectivity lifecycle, persistence, session isolation, and the React-free contract. The unified Vireo Storybook contains executable examples under **Infrastructure**; every displayed source file is the same TypeScript module Storybook executes.

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@vireocodedev/infrastructure",
+  "version": "0.2.0",
+  "description": "React-free browser infrastructure primitives for validated HTTP transport, connectivity, persistence, and execution-mode-aware services.",
+  "type": "module",
+  "sideEffects": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vireocodedev/starter.git",
+    "directory": "packages/infrastructure"
+  },
+  "keywords": [
+    "infrastructure",
+    "network-status",
+    "signals",
+    "http",
+    "starter"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./network-status": {
+      "types": "./dist/network/appNetworkStatus.d.ts",
+      "import": "./dist/network/appNetworkStatus.js"
+    },
+    "./pagination": {
+      "types": "./dist/http/pagination.d.ts",
+      "import": "./dist/http/pagination.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite build --watch --mode watch",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "@preact/signals-core": ">=1.8",
+    "axios": ">=1.7",
+    "zod": ">=4.4 <5"
+  },
+  "devDependencies": {
+    "@preact/signals-core": "^1.14.4",
+    "axios": "^1.19.0",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "vite": "^8.2.2",
+    "vite-plugin-dts": "^5.0.3",
+    "vitest": "^4.1.11",
+    "zod": "^4.4.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org"
+  }
+}