@vireocodedev/shell 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,65 @@
+# @vireocodedev/shell
+
+Framework-free contracts for application sitemap construction, navigation metadata, authentication redirects, and browser overlay-history coordination.
+
+## Install
+
+```bash
+npm install @vireocodedev/shell zod
+```
+
+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.
+
+## Primary workflow
+
+```ts
+import {
+  createShellSitemap,
+  defineShellConfig,
+  defineShellPages,
+  defineShellSections,
+  shellNavigation,
+} from "@vireocodedev/shell";
+
+const pages = defineShellPages({
+  dashboard: { routePath: "", label: "Dashboard", icon: "home" },
+  customer: { routePath: ":customerId", label: "Customer", permission: "customers:view" },
+});
+
+const sections = defineShellSections({ customers: { routePath: "customers", label: "Customers" } });
+const sitemap = createShellSitemap([
+  pages.dashboard,
+  { node: sections.customers, children: [pages.customer] },
+] as const);
+
+export const shellConfig = defineShellConfig(
+  {
+    mode: "dashboard",
+    sitemap,
+    entryPage: pages.dashboard,
+    navigation: { authenticated: [shellNavigation.item(pages.dashboard)] },
+  },
+  { permissions: ["customers:view"] },
+);
+
+sitemap.getPath(pages.customer, { customerId: 42 }); // /customers/42
+```
+
+## Ownership boundary
+
+Shell is deliberately independent of React, React Router, MUI, TanStack Query, PWA plugins, and Starter UI. It describes an application shell; it does not render one.
+
+Applications own router adaptation, permission evaluation, responsive layouts, PWA prompts, unsaved-change prompts, and navigation presentation. Reusable React presentation belongs in `@vireocodedev/ui`, not this package.
+
+## Public areas
+
+- Sitemap: immutable page and section definitions, a flattened route registry, typed path resolution, redirects, and duplicate detection.
+- Config and navigation: serializable navigation intent plus Zod-backed validation of modes, mounted pages, identifiers, and permission registries.
+- Authentication redirects: router-neutral internal return-path creation and open-redirect protection.
+- Overlay history: pure stack reconciliation and an instance-scoped observable registry; applications adapt its actions to their router.
+
+Importing the package creates no global store, browser listener, router, cache, or UI.

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@vireocodedev/shell",
+  "version": "0.2.0",
+  "description": "Framework-free contracts for application sitemap construction, navigation metadata, auth redirects, and overlay history.",
+  "type": "module",
+  "sideEffects": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vireocodedev/starter.git",
+    "directory": "packages/shell"
+  },
+  "keywords": [
+    "shell",
+    "navigation",
+    "sitemap",
+    "routing",
+    "starter"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.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": {
+    "zod": ">=4.4 <5"
+  },
+  "devDependencies": {
+    "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"
+  }
+}