@velarscript/cli 0.18.0 → 0.19.0

package/dist/version.d.ts

@@ -1,3 +1,3 @@
-export declare const VELAR_VERSION = "0.18.0";
+export declare const VELAR_VERSION = "0.19.0";
 export { VELAR_STANDARD_API_VERSION } from "@velarscript/core";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,3 +1,3 @@
-export const VELAR_VERSION = "0.18.0";
+export const VELAR_VERSION = "0.19.0";
 export { VELAR_STANDARD_API_VERSION } from "@velarscript/core";
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velarscript/cli",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "The VelarScript command-line compiler, dev server, test runner, and language server.",
   "license": "Apache-2.0",
   "type": "module",
@@ -30,13 +30,13 @@
     "velar": "./dist/cli.js"
   },
   "dependencies": {
-    "@velarscript/compiler": "0.18.0",
-    "@velarscript/core": "0.18.0",
-    "@velarscript/desktop": "0.18.0",
-    "@velarscript/node": "0.18.0",
-    "@velarscript/server": "0.18.0",
-    "@velarscript/web": "0.18.0",
-    "create-velar": "0.18.0",
+    "@velarscript/compiler": "0.19.0",
+    "@velarscript/core": "0.19.0",
+    "@velarscript/desktop": "0.19.0",
+    "@velarscript/node": "0.19.0",
+    "@velarscript/server": "0.19.0",
+    "@velarscript/web": "0.19.0",
+    "create-velar": "0.19.0",
     "esbuild": "^0.28.1",
     "playwright": "^1.58.2"
   }

package/skill/ai-skill-node.md

@@ -337,6 +337,11 @@ canonical HTTP/HTTPS origins. The default rejects any upgrade carrying
 intentional unrestricted policy. A rejected browser origin receives 403 before
 it consumes connection-queue capacity. Connections are pull-based. Always
 consume each connection's `next()`, handle backpressure, and stop the server.
+`closeInfo()` waits for the terminal handshake and returns the actual typed
+`WebSocketClose {code, reason}`; `next()` returning `null` alone does not expose
+why the connection ended. Application sessions should normally use
+server-target `velar/realtime.realtimeSession` instead of rebuilding their own writer and
+cleanup loops over this transport.
 
 ## Tests
 

package/skill/ai-skill-server.md

@@ -13,7 +13,7 @@ browser application activates `@velarscript/web`:
 ```json
 {
   "dependencies": {
-    "@velarscript/server": "0.18.0"
+    "@velarscript/server": "0.19.0"
   }
 }
 ```
@@ -177,6 +177,64 @@ dialect behavior, retry rules, and credentials remain independently installed
 application dependencies. Do not add SQLite, PostgreSQL, an ORM, or model
 syntax to `@velarscript/server` or `@velarscript/node`.
 
+## Typed realtime sessions
+
+Keep the physical socket and the application session separate. A declarative
+`@websocket` route receives `WebSocketConnection`; pass it to
+`realtimeSession` with the codec from the application's shared protocol
+package:
+
+```velar fragment
+import {Bytes} from "velar/binary"
+import {RealtimeFailure, RealtimeFailureAction, RealtimePeer, realtimeSession} from "velar/realtime"
+import {WebSocketConnection} from "velar/websocket"
+
+type Command:
+    operation: string
+
+type ServerEvent:
+    event: string
+
+def decode(message: string | Bytes) -> Command:
+    if message is string: return Json.parse(message, Command)
+    throw Error("Binary commands are not supported")
+
+def encode(event: ServerEvent) -> string | Bytes:
+    return Json.stringify(event)
+
+async def receive(command: Command, peer: RealtimePeer<ServerEvent>):
+    await peer.send({event: command.operation})
+
+async def failed(failure: RealtimeFailure, _peer: RealtimePeer<ServerEvent>):
+    print(failure.error)
+    return RealtimeFailureAction.close
+
+async def serveSession(connection: WebSocketConnection):
+    await realtimeSession(
+        connection,
+        {decode, encode},
+        receive,
+        failed=failed,
+        options={maxQueuedMessages: 64, maxQueuedBytes: 1_048_576, drainTimeout: 5s},
+    )
+```
+
+The session runs one sequential inbound handler and one writer over a bounded
+outbound mailbox. `peer.send(event)` waits for its own transport send;
+`peer.trySend(event)` returns `false` instead of waiting when the mailbox is
+full. `opened` may install a subscription and return an async cleanup function;
+cleanup runs exactly once before the writer finishes draining. `closed`
+receives the actual `WebSocketClose` code and reason.
+
+`RealtimeFailureAction.continue` skips one failed decode or command and keeps
+the session alive. Unrecoverable setup, transport, encode, and send failures
+close the session. Route authentication, authorization, room membership,
+subscription ownership, and application delivery semantics remain application
+policy. Do not report a command as durable merely because `send` completed:
+WebSocket is ordered but application delivery is still at-most-once unless the
+shared protocol adds message IDs, acknowledgements, resume cursors, and
+idempotent handling.
+
 ## Custom shared HTTP/WebSocket startup
 
 A service whose route table contains `@websocket` declarations may load the

package/skill/ai-skill-web.md

@@ -153,6 +153,51 @@ property unconditionally to override the component's outright, and declare it
 under a condition to refine that condition alone and leave the component's
 other values standing.
 
+## Realtime client
+
+`velar/websocket.connect` is the sole raw socket transport.
+`velar/realtime.realtimeClient` is the application layer: a typed codec,
+explicit lifecycle, finite reconnect policy, connection generations, and one
+callback where subscriptions can be rebuilt after reconnect.
+
+```velar fragment
+import {Bytes} from "velar/binary"
+import {RealtimeClient, RealtimeClientFailureAction, RealtimeOpen, realtimeClient} from "velar/realtime"
+
+type ServerEvent:
+    event: string
+
+type Command:
+    operation: string
+
+def decode(message: string | Bytes) -> ServerEvent:
+    if message is string: return Json.parse(message, ServerEvent)
+    throw Error("Binary events are not supported")
+
+def encode(command: Command) -> string | Bytes: return Json.stringify(command)
+
+async def opened(client: RealtimeClient<Command>, open: RealtimeOpen):
+    if open.reconnected: await client.send({operation: "resync"})
+
+export def liveClient(url: string) -> RealtimeClient<Command>:
+    return realtimeClient(
+        url,
+        {decode, encode},
+        async (event, _client) => print(event.event),
+        opened=opened,
+        failed=async (_failure, _client) => RealtimeClientFailureAction.reconnect,
+        options={reconnectDelays: [0ms, 1s, 2s, 5s], reconnectJitter: 0.2},
+    )
+```
+
+Call `await client.start()` from owned startup and `await client.close()` from
+cleanup. `whenOpen()` waits for the current or next generation;
+`whenClosed()` waits for terminal shutdown. The client does not queue or replay
+commands across a disconnect. Put message IDs, acknowledgements, resume
+cursors, and idempotency in the shared application protocol when stronger
+delivery is required. A URL function may refresh a signed URL on every attempt.
+Initial retry is off unless `retryInitial: true` is explicit.
+
 ## Storage and tests
 
 `velar/storage` stores JSON and validates on read. A generic type spelling is