@astralyn/sash 0.1.0 → 0.1.2

package/docs/frontend.md

@@ -1,125 +1,89 @@
-# Frontend Architecture & WebUI Design
-
-The WebUI is a Vue 3 application built with Vite and bundled into `dist/ui/`. sashd serves it at `http://127.0.0.1:19090/ui/`; `<root>/ui/index.html` can override the bundled dashboard.
-
----
-
-## 1. Build and Quality Gates
-
-- `npm run build:ui` calls the Vite Node API through `scripts/build-ui.mjs`.
-- `npm run typecheck:web` runs `vue-tsc`, including Vue templates.
-- `npm test` runs server type checking, WebUI type checking, backend tests and WebUI TypeScript tests.
-- Biome checks WebUI TypeScript and Vite configuration. Vue templates are type-checked by `vue-tsc` and compiled by Vite.
-- Vite 6 builds the bundled dashboard on the declared Node.js 24 baseline.
-- CI runs lint, server/WebUI type checks, all tests, production builds and actual tarball pack/install/CLI/UI smoke on Windows, macOS and Linux with Node.js 24.
-
----
-
-## 2. Source Layout
-
-```text
-web/src/
-├── api/index.ts                  typed REST client and WebSocket reconnect logic
-├── components/
-│   ├── AppSidebar.vue
-│   ├── ConfirmDialog.vue
-│   ├── Icon.vue                  semantic icon wrapper
-│   ├── icons.ts                  tree-shaken Remix Icon component mapping
-│   ├── ProxyGroupSection.vue     reusable group header/node grid
-│   ├── TrafficChart.vue
-│   └── ...
-├── i18n/                         Chinese source messages and typed English mirror
-├── stores/index.ts               runtime state, refresh actions and polling
-├── stores/state-ownership.ts     pure generations, cleanup and sync helpers
-├── styles/main.css               design tokens and shared utility/component styles
-├── types/index.ts                core-controller response types; daemon types are shared
-├── views/
-│   ├── OverviewView.vue          status, traffic, modes and proxy groups
-│   ├── ProfilesView.vue          download/import/update/select/delete profiles
-│   ├── LogsView.vue
-│   ├── ConnectionsView.vue
-│   ├── RulesView.vue
-│   └── SettingsView.vue
-├── App.vue                       shell, view selection and stream lifecycle
-├── theme.ts                      persisted system/light/dark theme state
-└── router.ts                     small hash router
-```
+# Frontend Architecture
+
+Sash retains its Vue 3 / Vite WebUI, built into `dist/ui/` and served by the daemon. Existing LXGW WenKai Lite font assets, appearance and Unicode-range splitting remain unchanged. No framework replacement or new UI/state framework is introduced.
 
-The shell follows a classic compact desktop-console layout: a 25px title strip sits above a 170px text-navigation sidebar with live traffic, recessed active-item geometry, runtime and Core status. Below 900px it becomes a compact title strip plus safe-area-aware bottom navigation. Light and Dark themes use flat neutral surfaces, dense rows, restrained shadows and distinct mode/semantic state colors. Profiles use a full-width download toolbar and compact profile grid; Logs use an edge-to-edge stream; Connections use colored metadata tags; Settings use labeled flat sections. Overview intentionally remains a roughly one-third/two-thirds combined General + Proxies workspace: common runtime controls and the GLOBAL/RULE/DIRECT selector stay on the left while the mode-driven proxy groups or DIRECT state render on the right. `styles/main.css` owns theme tokens, component states and reduced-motion behavior without a runtime-loaded UI dependency. Functional icons use selected, tree-shaken `@remixicon/vue` line components behind the local semantic `Icon.vue` API; the Sash brand mark remains project-owned. `THIRD_PARTY_NOTICES.md` records the bundled Vue MIT and Remix Icon notices, and the complete Remix Icon License v1.0 remains in `docs/remix-icon-license.txt`; both are included in the npm tarball. Long connection and rule sets remain paginated and switch to narrow-screen layouts.
+## State ownership
 
-Daemon/profile contracts live in `src/contracts.ts` and are imported as types by both `src/daemon-client.ts` and the WebUI. This prevents manually duplicated `SashStatus` and profile response shapes.
+`stores/state.ts` is the single shared shallow-reactive state. Large collections are replaced by reference. `stores/index.ts` only exports the public actions/selectors; it is not another state store.
 
----
+| Module | Responsibility |
+| --- | --- |
+| `stores/runtime-actions.ts` | Non-overlapping status polling, boot changes and settings actions |
+| `stores/profile-actions.ts` | Saved profile mutations and metadata refresh |
+| `stores/core-actions.ts` | Independent Core resource loads and mode/node/connection controls |
+| `stores/state-ownership.ts` | Request generations, runtime identity and pure selectors |
+| `stores/telemetry.ts` | Traffic history and batched, bounded log records |
+| `api/session.ts` | One-time bootstrap, per-tab session and daemon identity |
+| `api/index.ts` | Shared daemon client, Core queries and streams |
 
-## 3. Runtime State Ownership
+Three values determine refresh ownership:
 
-`web/src/stores/index.ts` owns status, profiles, proxy groups, rules, connections, traffic history, manual delay results, logs, operation flags and toasts. Pure ownership/generation helpers live in `web/src/stores/state-ownership.ts` and are covered by browser-free `node:test` tests. A pinned `happy-dom` dev dependency supplies the minimal DOM behavior harness for mounting a real Vue `createApp` render path and asserting reactive notice transitions; no second test runner or coverage-only gate is introduced.
+- `daemon.bootId`: a new daemon invalidates old authorization and metadata revision comparisons.
+- `revisions.profiles`: saved-state changes refresh profile metadata. It does not invalidate Core resources.
+- `revisions.runtime`: with `bootId`, identifies the Core runtime. Replacement clears Core resources, traffic and manual latency results.
 
-Canonical actions include:
+Each resource has its own loaded flag and error. A failed rules query does not discard working node data. Failures for the same runtime retain prior data and show degradation; a new runtime cannot inherit old data. Per-domain request generations discard late successes and errors. Mutation results from a replaced daemon/Core cannot overwrite its successor.
 
-- `refreshStatus()`
-- `refreshConnections()`
-- `refreshProxies()`
-- `refreshProfiles()`
-- `refreshRuntimeState()`
-- profile mutation actions such as `updateProfile()` and `activateProfile()`
-- runtime intent actions such as `setOutboundMode()` and `selectGroupProxy()`
-- `startRuntimePolling()`
+## Refresh and performance
 
-Polling is self-scheduling with `setTimeout` after the previous cycle completes. It slows to a 15-second interval while the page is hidden and refreshes immediately after returning to the foreground. Domain request generations discard responses made stale by a newer refresh or user mutation. Core-specific API calls are made only after status reports `running && healthy`.
+Status polls every two seconds after the previous cycle finishes. Hidden or unauthorized tabs use a slower interval; returning to the foreground refreshes promptly. Session initialization runs on entry/reconnect, with public status boot identity detecting daemon restarts.
 
-Daemon reachability, profile revision and Core snapshots have separate ownership. A successful `/sash/status` keeps the daemon online even when a downstream Core gateway request returns 502. Profiles track their last fetched daemon revision independently and refresh on revision changes even while Core is stopped. A daemon restart resets that revision comparison.
+| Visible page | Core requests |
+| --- | --- |
+| Overview | Config/mode and proxies approximately every third cycle; connections approximately every fifth cycle |
+| Connections | Connections each cycle |
+| Rules | Rules on entry/runtime change, then cached |
+| Profiles / Settings | No background Core tables |
+| Logs | Log stream while visible |
 
-The Core owner is the daemon boot plus Core PID/start time. A stopped/unhealthy Core or unreachable daemon clears proxy groups, rules, connections/totals and traffic rates/history. A same-owner Core API failure preserves the last complete configs/proxies/rules/connections snapshot, marks it degraded and retries; a changed owner clears the old snapshot before fetching, so failed replacement data cannot be shown under the new owner. Profile revision changes request a new snapshot without prematurely discarding same-owner data.
+Entering a page loads its resources immediately. Profile saves only refresh management metadata. Explicit Apply refreshes the resources visible after Core replacement. Traffic is one shared stream for visible consumers; traffic/log sockets pause when the page is hidden or the runtime/session is unavailable.
 
-Manual latency results are stored separately from polled proxy payloads. Normal proxy polling therefore preserves a test result; a successful profile snapshot generation or Core owner change invalidates stale delay results.
+Existing optimizations remain: async route/editor chunks, shallow collections, collapsed node groups unmounting their cards, paginated connections/rules, separate manual latency results, and roughly 100 ms log batches capped at 600 rows. Font slices load only for rendered glyph ranges.
 
-Views call store actions rather than maintaining separate copies of status/proxy/rule refresh orchestration. Same-domain controls use store operation flags, while independent group/node latency tests remain concurrent.
+## Views and shared controls
 
----
+`App.vue` owns the shell, route composition, session gate, global pending-configuration bar and stream lifetime. Existing Overview, Profiles, Logs, Connections, Rules and Settings pages remain.
 
-## 4. Profiles and Overview Components
+`CoreControls.vue` and `useCoreControl()` share busy state and Apply/start/stop actions across the Overview, Settings and pending bar. Applying while running asks for confirmation because it restarts Core. Stopping Core keeps management open.
 
-The Profiles page provides:
+Profile selection and edits are saved first. The pending bar indicates that the running configuration differs. Overview displays the applied profile/port; Profiles shows the saved selection. The YAML editor submits the content revision read on open, preventing another tab's later edits from being overwritten. The raw `sash.json` editor is removed.
 
-- URL download and clipboard paste
-- local YAML import
-- Update All and per-profile update
-- active profile selection
-- quota/expiry display from provider metadata
-- persisted update errors
-- delete confirmation
+Settings drafts remain local until Save and survive status polling. A saved port/LAN change waits for Apply. The system-proxy switch performs its own operation and remains available for recovery when Core is stopped. The login-startup card uses the observed OS registration and explicit enable/remove actions.
 
-The Overview proxy panel uses `ProxyGroupSection.vue` for manual, automatic and GLOBAL groups. This keeps node-card rendering, delay labels, UDP/current markers and group test controls in one component. Group and node latency tests track independent in-flight sets, so tests for different groups/nodes can run concurrently. Mode and proxy-selection mutations are latest-request-wins and disable only their matching control domain.
+`PageHeader`, `ProxyGroupSection`, the shared code editor, pagination, confirmation service and focus/scroll-lock composables remain reusable building blocks. Light/dark themes, Chinese/English copy and mobile navigation are retained. There is no generic table framework or event bus.
 
-System proxy controls are target-state based: enabling requires a running, healthy Core; disabling remains available when desired/applied/OS-observed state indicates cleanup may still be required, including while the Core is stopped.
+## Authorization and transport
 
----
+`src/contracts.ts` and `src/sash-client.ts` define the browser-safe daemon protocol. Runtime imports do not pull Node-specific implementations into the browser. Core types describe only the data the UI uses.
 
-## 5. API and Streaming
+The browser consumes and immediately removes the private handoff fragment, exchanges it once, and stores its session with the issuing daemon identity in `sessionStorage`. Concurrent initialization shares the exchange; storage denial falls back to memory. Old responses cannot resurrect or revoke a newer session. A bare URL shows connection instructions and never gains control through public health.
 
-`web/src/api/index.ts`:
+Core HTTP requests carry `X-Sash-Token`; streams use private WebSocket subprotocol authentication. The daemon replaces these credentials with its internal controller bearer. Frames require finite nonnegative counters or known textual log records. Each stream owns one reconnect timer and ignores frames from older runtime generations.
 
-- distinguishes JSON and `204 No Content` endpoints through overloads rather than `undefined as T`;
-- reads an error response body once and surfaces JSON or plain-text messages;
-- parses WebSocket frames separately from consumer callbacks, validates finite non-negative traffic counters and known textual log records, and silently drops malformed frames;
-- maintains at most one reconnect timer per stream;
-- binds stream callbacks to the current runtime generation and stops stream ownership when the daemon session or healthy Core is unavailable;
-- resets stale traffic rates/history when the current traffic stream disconnects without allowing an older socket's close event to clear a replacement stream;
-- sends `X-Sash-Token` on HTTP requests after initialization.
+## Development and verification
 
-Streams:
+```sh
+npm run typecheck
+npm run lint
+npm test
+npm run build
+node --import tsx scripts/ui-verify.mts
+node --import tsx scripts/profile-ui-verify.mts
+node --import tsx scripts/web-auth-ui-verify.mts
+node --import tsx scripts/autostart-ui-verify.mts
+```
 
-- `api.connectTraffic(callback)` → `/core/api/traffic`
-- `api.connectLogs(callback)` → `/core/api/logs`
+The browser scripts use isolated data, non-default ports and fake Core/OS adapters in Chromium and Firefox. The main script checks saved/applied state, authentication, font loading, request counts and layouts with 300 nodes, 10,000 rules and 500 connections. Other scripts retain focused profile, private-file authorization and autostart interaction coverage. These are behavioral checks, not a real-Core CPU/memory benchmark.
 
-The controller secret is never available to browser code; sashd injects it server-side.
+For local source development:
 
----
+```sh
+node scripts/dev.mjs web
+node scripts/dev.mjs build    # rebuild UI, then refresh the page
+node scripts/dev.mjs stop     # before loading backend changes
+node scripts/dev.mjs web
+```
 
-## 6. Interaction State
+The launcher uses a separate `-dev` data directory and initial ports `18890`, `18990`, `28990`. `SASH_DEV_HOME` selects another absolute directory. It passes development defaults to the daemon without writing settings itself. `web` starts management only; `restart` applies configuration to Core. A backend code change requires stopping and starting the daemon.
 
-- Settings derive mixed-port dirty state by comparing the draft with the last committed value, preserve a genuinely edited draft across polling, and expose an explicit reset action. Successful `allow-lan` and TUN responses commit the returned settings snapshot directly before any follow-up refresh. TUN controls separately derive active, inactive, unverified, pending-start and desired/runtime-mismatch presentation from `settings.tun` plus `core.tunActive`; failed online activation never advances the committed switch, and the returned error explains that the whole Sash daemon—not only its Core child—must be restarted with elevated privileges.
-- Logs receive monotonic IDs before entering the capped 600-row buffer, providing stable Vue keys and an update sequence even when length remains constant.
-- The global confirm service settles a previous pending Promise before opening another dialog; Escape, route changes and component unmount cancel the active confirmation.
-- The global banner distinguishes an unreachable daemon from a degraded same-owner Core snapshot and an unavailable new-owner snapshot.
+The font build continues to use `cn-font-split`, native subsetter `default@7.6.8` and the scoped `koffi: 2.16.3` override. Install the native subsetter explicitly when dependency lifecycle scripts are disabled. Bundled Vue/Remix Icon licenses remain in `THIRD_PARTY_NOTICES.md` and `docs/remix-icon-license.txt`.

package/docs/usage.md

@@ -1,227 +1,129 @@
 # Sash User & Operations Guide
 
-Sash is a lightweight command-line companion and web dashboard for managing a rule-based network core.
+Sash is a lightweight network toolbox for developers, learning and research, with a CLI and built-in web dashboard. Windows is the primary desktop platform.
 
----
-
-## 1. Quick Start
+## Start and configure
 
 ```sh
-sash start
-sash web        # open the dashboard: download a subscription, pick nodes, toggle the system proxy
+sash web         # start management and authorize the browser; Core stays stopped
+sash start       # install Core if missing, apply saved configuration and start
 sash status
+sash stop        # restore the prior proxy, stop Core and exit the daemon
 ```
 
-Profiles, the system proxy and all runtime settings are managed from the web dashboard; the CLI covers lifecycle, logs and upgrades.
-
----
-
-## 2. CLI Command Reference
-
-### Lifecycle Management
-
-| Command | Description |
-| :--- | :--- |
-| `sash start` | Install missing components, ensure the background daemon is running, then reconcile/start the core. It is safe to repeat. |
-| `sash stop` | Restore the pre-Sash system proxy, stop the Core and shut down the daemon; exits with an error if safe shutdown cannot be verified. |
-| `sash restart` | Restart the whole runtime: the daemon exits through its maintenance boundary and a fresh daemon starts the core. |
-| `sash status [--json]` | Show daemon/core state, active profile, endpoints and system proxy state; incomplete observations exit with code 2. |
-| `sash logs [-n N] [-f] [--errors] [--daemon]` | View core or daemon logs; `-f` follows new output. |
-
-### Status JSON and exit codes
-
-`sash status --json` emits the versioned `schemaVersion: 1` contract below. Unobservable runtime values are `null`; they are never changed to `false` merely because a query timed out.
-
-```json
-{
-  "schemaVersion": 1,
-  "complete": true,
-  "healthy": true,
-  "queryError": null,
-  "daemon": {
-    "state": "healthy",
-    "running": true,
-    "healthy": true,
-    "pid": 1234,
-    "port": 19090
-  },
-  "core": {
-    "running": true,
-    "healthy": true,
-    "pid": 1235,
-    "version": "v1.19.30",
-    "installedVersion": "v1.19.30"
-  },
-  "systemProxy": {
-    "desired": false,
-    "daemonApplied": false,
-    "osObserved": {
-      "supported": true,
-      "enabled": false,
-      "server": null,
-      "details": null
-    }
-  },
-  "uiInstalled": true,
-  "endpoints": {
-    "mixedProxy": "127.0.0.1:7890",
-    "controller": "127.0.0.1:9090",
-    "daemonApi": "http://127.0.0.1:19090",
-    "dashboard": "http://127.0.0.1:19090/ui/"
-  },
-  "activeProfile": null,
-  "tun": {
-    "desired": false,
-    "active": false
-  },
-  "paths": {
-    "root": "<data directory>",
-    "config": "<data directory>/config.yaml"
-  }
-}
-```
+In **Profiles**, import YAML or download a remote profile, then select it. Selection, content edits, downloads and scheduled updates are saved without changing the running Core. Click **Apply configuration** to use the saved configuration. This restarts Core and briefly interrupts connections. Overview shows the profile and port actually applied.
 
-`healthy` is the observed daemon/Core controller health and is `null` when daemon runtime status cannot be queried. `complete` covers observability of all contract fields; `queryError` explains an incomplete result. Exit codes are stable:
+If validation fails, the previous Core keeps running. If starting the new configuration fails, your saved edits remain and the dashboard stays available for correction. There is no automatic rollback of saved edits.
 
-| Exit code | Meaning |
-| :--- | :--- |
-| `0` | The status is complete, including a known stopped state. |
-| `2` | Status output was produced, but daemon/Core/OS state could not be fully observed. |
-| `1` | The command itself failed, for example because local state is corrupt. |
+## Commands
 
-Text output follows the same distinction: an unresponsive daemon is reported as unavailable, never with a success marker. `sash status` prints separate daemon, desired, daemon-applied and OS-observed proxy lines and uses exit code 2 when the daemon is alive but unresponsive.
+| Command | Behavior |
+| --- | --- |
+| `sash start` | Ensure management exists; start with saved configuration if stopped. Repeated starts check the running Core and proxy intent. |
+| `sash restart` | Apply saved configuration and restart Core; keep the daemon and browser sessions. |
+| `sash stop` | Restore proxy, stop Core and exit management. Report an error if safe shutdown cannot be verified. |
+| `sash status [--json]` | Read runtime, endpoint, saved profile, proxy and autostart observations. Bare `sash` does the same. |
+| `sash web` | Start management if needed and authorize/open the dashboard. |
+| `sash web --no-open` | Start management and print its address without authorizing a browser. |
+| `sash update [--version TAG]` | Download, verify and install a Core release through the daemon. |
+| `sash auto [on\|off\|status]` | Set or inspect Windows login startup. No argument means status. |
+| `sash logs [-n N] [-f] [--errors] [--daemon]` | Read Core or daemon logs; follow waits for creation and handles rotation. |
+| `sash logs --startup [-n N] [-f]` | Read login attempts, including settings errors before daemon startup. |
+| `sash version` | Print the package version. |
 
-### Log following
+WebUI **Stop Core** keeps the management process open. To reload updated Sash program code, use stop followed by start/web. `restart` only replaces Core.
 
-`logs -f` behaves like a bounded `tail -F`: it waits when the selected file or log directory does not exist yet, follows appended bytes, restarts at byte zero after truncation or file replacement/rotation, and releases its watcher/timer on SIGINT or SIGTERM. `-n` accepts only canonical positive decimal integers such as `1` or `100`; zero, signs, whitespace, fractions, numeric prefixes and values above JavaScript's safe-integer limit are rejected.
+## Browser access
 
-Sash does not blindly turn off an existing proxy. It stores a private ownership journal before takeover and restores only while managed OS values still match the original/Sash transition. If another application changes those values, Sash refuses to overwrite them. Windows and macOS include manual and automatic proxy state; Linux system-proxy automation currently requires GNOME `gsettings`.
+Run `sash web` as the same user and with the same `SASH_HOME` as the instance. A private local handoff authorizes the browser without printing credentials. It expires after 90 seconds and works once; rerun the command if needed.
 
-### Web Dashboard
+An authorized tab survives refresh and Core restarts/updates. A daemon restart needs a new authorization. If browser storage is disabled, authorization lasts only for the current page. Opening a bare dashboard address displays connection instructions.
 
-| Command | Description |
-| :--- | :--- |
-| `sash web` | Open `http://127.0.0.1:19090/ui/`. |
-| `sash web --no-open` | Print the dashboard URL without opening a browser. |
+## Settings and profiles
 
-### Profiles
+The Settings page saves the mixed proxy port and LAN access for the next Apply. The system-proxy switch takes effect separately and requires a healthy Core to enable. A failed disable keeps the saved off intent; retry it after resolving the OS problem.
 
-Profiles are managed from the WebUI Profiles page: download from a subscription URL, import a local YAML file, update one or all profiles, rename, edit content, switch the active profile and delete. Remote profiles use the update interval advertised by the provider, defaulting to 24 hours. The daemon checks for due updates every 15 minutes.
+Remote profiles use the provider's update interval, defaulting to 24 hours. The daemon checks for due updates every 15 minutes. Updates save new content and indicate pending Apply. Identical content does not create a new content revision. Rename and reorder do not affect running data or latency results.
 
-### Settings
+The profile editor rejects a save if another edit changed its content revision. Reopen the current content before retrying. The raw application settings file has no online editor.
 
-Runtime settings (`mixed-port`, `tun`, `allow-lan`, `system-proxy`) are managed from the WebUI Settings page, and the entire `sash.json` can be edited as JSON from the same page ("Edit settings file"); invalid documents are rejected without touching the disk. `daemonSecret` changes apply immediately; `daemonPort` changes are saved but require a manual `sash restart` to rebind the listener.
+Login startup is managed through the OS registration, not a boolean in the settings file. Enabling it requires a direct global npm installation. See [Automatic Startup](./autostart.md).
 
-### Maintenance & Upgrades
+## State format and data
 
-| Command | Description |
-| :--- | :--- |
-| `sash update [--version V] [--force]` | Download and validate a replacement core, then swap it in transactionally. |
-| `sash upgrade [--version V]` | Upgrade the Sash package through npm; requires `sashd` to be stopped first. |
-| `sash version` | Print the Sash package version. |
+This branch requires a new schema-2 manifest and provides no migration from older releases. Stop the old instance using its existing installation, keep any profile YAML you need, then use a fresh data directory and import those files normally. Old state is never silently overwritten.
 
-Core updates download and validate before shutdown, then use an authenticated maintenance request that atomically snapshots whether Core was running while restoring proxy state and stopping `sashd`. After daemon exit, a durable update journal records the previous/target install records before the executable swap. A previously running Core is health-checked immediately; when Core was stopped, `<core>.bak` and the journal remain until the next managed `sash start` passes controller health/version checks. A failed first start restores the previous binary and install record before attempting to restart it. Downloads require official GitHub SHA-256 asset metadata; mirrors are accepted only as transports for bytes matching that digest, and all mirror/redirect/body attempts share a bounded absolute deadline. Archives are capped at 128 MiB, Windows ZIPs must contain the expected upstream Core executable basename, staged binaries must report the exact requested version, and the staged Core validates the freshly generated active configuration before publication.
+`sash.json` contains `{schemaVersion: 2, revision, settings, profiles}`. `profiles` contains the saved `activeId` and metadata list. The following keys live inside `settings`:
 
-`sash upgrade --version` accepts only a strict npm semver such as `1.2.3` (without a `v` prefix) or a safe dist-tag such as `latest`/`next`. Package specs, paths, ranges and control characters are rejected.
+| Key | Initial value | Meaning |
+| --- | --- | --- |
+| `mixedPort` | `7890` | HTTP/SOCKS mixed proxy port |
+| `allowLan` | `false` | Accept proxy traffic from other devices |
+| `systemProxy` | `false` | Desired Windows system-proxy state |
+| `controller` | `127.0.0.1:9090` | Internal loopback controller address |
+| `daemonPort` | `19090` | Management API and dashboard port |
+| `secret` | random | Private controller credential |
+| `daemonSecret` | random | Private CLI credential |
 
----
+Controller/daemon addresses and credentials can be edited only while Sash is stopped, then read at daemon startup. All three ports must differ. Secrets cannot be blank. Invalid, unknown-field, oversized or unsupported-format state is rejected intact. There are no TUN or legacy subscription settings.
 
-## 3. Configuration Reference (`sash.json`)
-
-| Key | Default | Description |
-| :--- | :--- | :--- |
-| `schemaVersion` | `1` | On-disk settings schema; managed by Sash. |
-| `mixedPort` | `7890` | Local HTTP/SOCKS5 mixed inbound port. The CLI key is `mixed-port`. |
-| `controller` | `127.0.0.1:9090` | Internal controller listen address; only loopback hosts are accepted. |
-| `daemonPort` | `19090` | Daemon API and WebUI port. |
-| `secret` | *(random)* | Internal controller secret. It is never returned by the public status API. |
-| `daemonSecret` | *(random)* | CLI bearer secret for state-changing daemon requests. |
-| `systemProxy` | `false` | Desired OS-level system proxy state. |
-| `tun` | `false` | Enable the TUN inbound; requires elevated privileges. |
-| `allowLan` | `false` | Accept proxy traffic from other devices. |
-
-A legacy `subscriptionUrl` key is migrated once into `profiles/index.json` and then removed. It has priority over legacy `config.yaml` import. If no `profiles/index.json` has ever been created, startup/offline initialization may import an existing `config.yaml` once as the active local profile named `Imported config` (`url: ""`, updates disabled). A present empty index opts out. To avoid importing Sash's own generated default, the file must be valid core-format YAML and contain non-default routing content after managed keys are removed: nonempty proxies/providers, or nonempty rules/groups differing from the DIRECT-only default. The runtime `config.yaml` is kept unchanged during import; later profile application re-renders and validates it. Invalid YAML/config fails closed without overwriting the file.
+| Platform | Default directory |
+| --- | --- |
+| Windows | `%LOCALAPPDATA%\Sash` |
+| macOS | `~/Library/Application Support/Sash` |
+| Linux | `$XDG_DATA_HOME/sash` or `~/.local/share/sash` |
 
-Installed core version metadata lives in `state/install.json`, not in `sash.json`.
+Use an absolute `SASH_HOME` to select another directory. Use a local filesystem supporting atomic rename and hard links.
+
+```text
+sash.json                       settings, profiles, selection and saved-state revision
+profiles/<id>/<revision>.yaml    immutable source content
+runtime/config.yaml             generated runtime configuration
+bin/                            Core executable and temporary update backup
+state/install.json              installed version
+state/core-update-transaction.json  active binary update/recovery
+state/system-proxy.json         original proxy snapshot and recovery phase
+state/sash.pid, state/sashd.pid  process discovery records
+state/sashd*.lock               daemon singleton/startup ownership
+logs/                           Core, daemon and login diagnostics
+ui/                             optional custom dashboard override
+```
 
-Malformed, future-version or unknown-field `sash.json` documents and malformed `profiles/index.json` files are rejected without being overwritten. Secrets cannot be blank or contain control characters, the controller must remain loopback-only, and the mixed, controller and daemon ports must all differ. Repair or move a damaged file explicitly instead of relying on silent defaults.
+The manifest and sources use atomic publication. Old source revisions may be cleaned after successful saves; this is not a version-history feature. Do not edit generated runtime configuration. POSIX private state/logs use `0600`.
 
-Settings changes are prepared as an all-or-nothing candidate: active configuration is validated before settings/config publication, and a failed restart restores the previous candidate where possible. Turning the system proxy off persists the desired off state before OS cleanup; if cleanup fails, toggle the system proxy off again from the WebUI after resolving the OS error.
+## Updates
 
----
+Core updates keep the dashboard available and preserve whether Core was running. Even an initially stopped update performs a temporary startup/health check, then stops again. `.bak` is retained until the new binary passes verification and the original running state is restored. Failure rolls back the executable and install record; saved profiles/settings are not part of this transaction.
 
-## 4. TUN Mode
+Downloads require official SHA-256 metadata, trusted HTTPS origins and bounded extraction. If verification cannot complete, the update fails rather than executing unverifiable bytes.
 
-TUN requires the whole Sash daemon to run with elevated privileges. Stop the current daemon and save the setting while Sash is offline — toggle it in the WebUI Settings page before stopping, or set `"tun": true` in `sash.json` directly:
+Update Sash itself through npm:
 
 ```sh
 sash stop
-# ensure TUN is on (WebUI Settings page, or edit sash.json)
-```
-
-On Windows, open PowerShell as Administrator:
-
-```powershell
+npm install -g @astralyn/sash
 sash start
+sash web
 ```
 
-The default `%LOCALAPPDATA%\Sash` data root remains the same when the current Windows user elevates. Only copy an explicitly customized `SASH_HOME` into the Administrator shell.
+`sash upgrade` and `sash update --force` are removed. Damaged installations are diagnosed and preserved; use a clean data directory for reinstalling after stopping the existing instance.
 
-On macOS or Linux, `sudo` can change the default home directory. Read the current data root and pass it explicitly while starting Sash as root:
+## Status and troubleshooting
 
-```sh
-sash status  # note the printed data root
-sudo env SASH_HOME='<data root printed above>' "$(command -v sash)" start
-```
-
-While that elevated daemon is running on macOS or Linux, use the same `sudo` and `SASH_HOME` prefix for later lifecycle commands such as `status` or `stop`, so they target the same runtime and can read its protected state.
-
-If TUN was already saved as on, just start Sash elevated. Because a full `sash restart` replaces the daemon itself, running it from the elevated shell is equivalent to `sash stop` + `sash start` here; restarting only the Core from the dashboard does not elevate `sashd`.
-
-Sash distinguishes the desired setting from the Core's actual runtime state: `sash status` reports `on (active)`, `on (inactive)`, `on (unverified)` or `on (runtime unknown)`, and `sash status --json` reports `tun.desired` separately from `tun.active` (`true`, `false` or `null`). Privilege guidance is shown only after a responsive, healthy running Core explicitly reports inactive or unverified TUN state.
-
-When a running Core is switched from TUN off to on, Sash reads back `tun.enable` from the Core before committing the setting. If the Core remains inactive or cannot be verified, the settings/config transaction and prior runtime are restored. An inactive result includes the platform-appropriate elevated `sash restart` instructions above. A TUN setting saved while the Core is stopped can only be verified on the next start; startup leaves the ordinary proxy Core available and reports any inactive or unverified TUN state explicitly. If an elevated start still leaves TUN inactive, inspect the Core error log.
-
-Do not enable TUN in automated smoke tests.
-
----
+`sash status --json` uses `schemaVersion: 2`. It includes `complete`, `healthy`, `queryError`, daemon/Core state, desired/applied/observed proxy state, autostart, endpoints, saved active profile and paths. Unknown observations remain `null`; no TUN fields are emitted. The running proxy endpoint comes from applied settings.
 
-## 5. Data Directory Layout
-
-| Platform | Default Path |
-| :--- | :--- |
-| Windows | `%LOCALAPPDATA%\Sash` |
-| macOS | `~/Library/Application Support/Sash` |
-| Linux | `$XDG_DATA_HOME/sash` or `~/.local/share/sash` |
-
-Override the root with an absolute `SASH_HOME` path.
-
-- `bin/`: installed core executable; `.bak` is retained during an update transaction.
-- `config.yaml`: active runtime configuration rendered from the active profile or the DIRECT-only default; qualifying pre-profile files are preserved during one-time import.
-- `sash.json`: Sash settings and local control secrets.
-- `profiles/index.json`: profile metadata and active profile id.
-- `profiles/<id>.yaml`: validated local copy of each downloaded/imported profile.
-- `state/sashd.pid`, `state/sash.pid`: atomic daemon/Core discovery records.
-- `state/system-proxy.json`: pre-takeover proxy snapshot and ownership phase.
-- `state/install.json`: canonical installed Core version record.
-- `state/core-install-transaction.json`: first-install publication journal; interrupted publishing rolls back, while a committed marker is only cleared.
-- `state/core-update-transaction.json`: previous/target install records and update phase; retained with `.bak` until managed runtime health and restoration succeed.
-- `state/*.lock`: daemon, runtime, mutation, settings and proxy ownership leases.
-- `logs/`: core and daemon stdout/stderr logs.
-- `ui/` *(optional)*: custom dashboard override.
-
-State files are written with mode `0o600` on POSIX where applicable. `SASH_HOME` must be on a local filesystem supporting atomic rename and hard links.
-
----
-
-## 6. Troubleshooting
-
-- **System proxy recovery is blocked:** another application changed managed values or the ownership journal is corrupt. Keep the Core running, inspect `state/system-proxy.json` and the current OS proxy, then repair explicitly; Sash will not overwrite an unrecognized state.
-- **Daemon/Core ownership is corrupt:** inspect `state/*.lock` and PID records. Sash intentionally fails closed instead of deleting uncertain ownership records.
-- **Profile update failed:** inspect the profile card's error or use its update button; generated candidates are checked by the installed Core before commit, and the last valid running config remains active on validation/reload failure.
-- **Corrupt settings/profile index:** repair the JSON file or move it aside; Sash intentionally does not overwrite corrupt state.
-- **Daemon errors:** `sash logs --daemon --errors`.
-- **Core errors:** `sash logs --errors`. Log tails and follow-mode reads use bounded chunks, so large logs do not require one whole-file allocation.
-- **Shutdown returned an error:** cleanup was not completed; the daemon remains listening and scheduled profile updates remain active. Resolve the reported proxy/Core issue and retry `sash stop`.
-- **Core binary/metadata mismatch:** Sash will not execute a binary unless `state/install.json` is valid and agrees that an installation exists. An interrupted `.unlock-probe` is restored automatically when it is the only copy; if both files exist with different bytes, Sash preserves both and fails closed. Inspect them explicitly or run `sash update --force` after resolving the conflict.
-- **Force a validated core reinstall:** `sash update --force`.
+| Exit code | Meaning |
+| --- | --- |
+| `0` | Complete observation, including a known stopped state |
+| `2` | Output produced, but some runtime/OS observation is unavailable |
+| `1` | The command failed, for example due to corrupt local state |
+
+- **Pending configuration:** click Apply or run `sash restart`. Saving alone does not change Core.
+- **Apply failed:** inspect the displayed error and `sash logs --errors`; correct the saved profile and apply again.
+- **Proxy restoration blocked:** keep the ownership journal and inspect the current Windows settings. Sash will not overwrite third-party changes or stop a healthy Core while restoration fails.
+- **Daemon ownership unknown:** inspect its logs and PID/lease records; Sash will not kill an unverified process or start a competitor.
+- **Interrupted update:** stop and start the daemon so its startup recovery can run. Corrupt or unrecognized backup/metadata files are preserved for inspection.
+- **Login startup failed:** read `sash auto status` and `sash logs --startup`; repair the entry with `sash auto on`.
+- **Shutdown failed:** the management API remains available for retry. Resolve the reported proxy/Core failure and repeat `sash stop`.
+
+Windows proxy/PAC restoration and login startup are the only desktop integrations. Basic Core/CLI operation remains portable. TUN and service mode are outside this branch; generated configuration always disables TUN and rejects a separate TUN listener.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@astralyn/sash",
-  "version": "0.1.0",
-  "description": "A lightweight command-line companion for a rule-based network core and its web dashboard. For developers and advanced users.",
+  "version": "0.1.2",
+  "description": "A network toolbox for developers, learning, and research, with a command-line companion and built-in web dashboard.",
   "license": "MIT",
   "author": "ming-kang",
   "type": "module",
@@ -47,8 +47,7 @@
     "network",
     "toolbox",
     "rules",
-    "dashboard",
-    "tun"
+    "dashboard"
   ],
   "publishConfig": {
     "access": "public"
@@ -56,23 +55,28 @@
   "dependencies": {
     "adm-zip": "^0.6.0",
     "commander": "^13.1.0",
-    "cross-spawn": "^7.0.6",
     "undici": "^7.29.0",
     "yaml": "^2.7.0"
   },
+  "overrides": {
+    "cn-font-split": {
+      "koffi": "2.16.3"
+    }
+  },
   "devDependencies": {
     "@biomejs/biome": "^2.5.5",
     "@codemirror/legacy-modes": "^6.5.4",
     "@codemirror/theme-one-dark": "^6.1.3",
     "@remixicon/vue": "^4.9.0",
     "@types/adm-zip": "^0.5.7",
-    "@types/cross-spawn": "^6.0.6",
     "@types/node": "^24.0.0",
+    "@types/sortablejs": "1.15.9",
     "@vitejs/plugin-vue": "^5.2.4",
     "cn-font-split": "^7.4.3",
     "codemirror": "^6.0.2",
     "happy-dom": "20.13.0",
     "playwright": "^1.62.1",
+    "sortablejs": "1.15.7",
     "tsx": "^4.19.3",
     "typescript": "^5.8.2",
     "vite": "^6.4.3",