@plurnk/plurnk-schemes-http 1.3.12 → 1.4.0

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export { default as Ws } from "./Ws.ts";
 export { default as Browser } from "./Browser.ts";
 export type { ChromiumEngine, ChromiumFactory, RenderResult } from "./Browser.ts";
 export { default as WebFetcher } from "./WebFetcher.ts";
-export type { WebFetchResult } from "./WebFetcher.ts";
+export { PROJECTION_ID_HEADER, WebMaterializationError } from "./WebFetcher.ts";
+export type { WebFetchResult, WebMaterializedResult } from "./WebFetcher.ts";
 export { default as Guard, GuardBlockedError } from "./Guard.ts";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,WAAW,CAAC;AAK5C,OAAO,EAAE,OAAO,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AAIxC,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,cAAc,CAAC;AAClD,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAGlF,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACxD,YAAY,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,OAAO,IAAI,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,WAAW,CAAC;AAG5C,OAAO,EAAE,OAAO,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AAGxC,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,cAAc,CAAC;AAClD,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAGlF,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAChF,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAC7E,OAAO,EAAE,OAAO,IAAI,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,16 +1,12 @@
-// Public API barrel for @plurnk/plurnk-schemes-http.
-// The default export is the scheme class plurnk-service registers at boot
-// (plugin discovery scans node_modules/@plurnk/* for `plurnk.kind === "scheme"`).
+// Public package surface. package.json owns plugin registration {§http-manifest}.
 export { default } from "./Http.js";
 export { default as Http } from "./Http.js";
-// The WebSocket scheme (#468/#473) — this package's second first-class scheme,
-// registered `wss` via package.json plurnk.schemes ({ export: "Ws" }); the `ws`
-// prefix rides it (core's schemeNameOf, mirroring https → http).
+// The registered WebSocket handler {§ws}.
 export { default as Ws } from "./Ws.js";
-// Standalone render foundation — exported so a future plurnk browser-
-// troubleshooting MCP package can sit on the same warm-Chromium pool.
+// Standalone render foundation {§render-lifecycle}.
 export { default as Browser } from "./Browser.js";
-// The guarded prefetch acquisition seam core's entrySink calls (#454).
+// Automatic entry-acquisition primitive {§prefetch} and its URL check.
 export { default as WebFetcher } from "./WebFetcher.js";
+export { PROJECTION_ID_HEADER, WebMaterializationError } from "./WebFetcher.js";
 export { default as Guard, GuardBlockedError } from "./Guard.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,0EAA0E;AAC1E,kFAAkF;AAClF,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,WAAW,CAAC;AAE5C,+EAA+E;AAC/E,gFAAgF;AAChF,iEAAiE;AACjE,OAAO,EAAE,OAAO,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AAExC,sEAAsE;AACtE,sEAAsE;AACtE,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,cAAc,CAAC;AAGlD,uEAAuE;AACvE,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAExD,OAAO,EAAE,OAAO,IAAI,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,WAAW,CAAC;AAE5C,0CAA0C;AAC1C,OAAO,EAAE,OAAO,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AAExC,oDAAoD;AACpD,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,cAAc,CAAC;AAGlD,uEAAuE;AACvE,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAEhF,OAAO,EAAE,OAAO,IAAI,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC"}

package/docs/http.md

@@ -1,60 +1,102 @@
 # http(s)://
 
-Fetch a URL. HTML is rendered (headless browser, post-JS) and returned as
-**markdown by default** (main content; nav/ads/chrome stripped). Non-HTML
-returns its readable content under the response `Content-Type`. Every request
-streams its response: status `102` now, then an ordinary fragmentless READ
-returns the sanitized body. Auxiliary transport/archive channels are never
-presented by default.
-
-Re-reading a URL without `<scope>` **revalidates** it: the prior fetch's validators (`ETag`/
-`Last-Modified`) go out on the next READ, and if the page is unchanged the
-stored copy is served without re-rendering — always fresh, but cheap when
-nothing changed. Within the operator's freshness window a re-read serves the
-stored copy directly, skipping even that check. You just READ again; there's
-no cache flag to manage.
-
-A scoped READ (`READ(url)<start,end>`) observes the already-materialized
-readable response without refetching it. If the URL has not been materialized,
-READ it once without a scope first.
-
-The HTTP method is the **op**:
-
-- `READ(http(s)://…)` — GET.
-- `SEND[200](http(s)://…):body:` — POST the body.
-- `EDIT(http(s)://…):body:` — PUT the body (replaces the whole resource; no `<L>`).
-- `KILL(http(s)://…)` — DELETE the resource.
-
-The ordinary URL is the model-facing markdown for HTML, or readable response
-content for other textual types. Diagnostic channels require explicit access:
-
-- `#html` — faithful rendered DOM for HTML (`text/html`)
-- `#header` — response status line + headers (`text/plain`)
-
-Request headers ride **inside the target** as trailing `{Key: value}` blocks —
-one header per block, so a value may contain commas/colons:
-
-```
-READ(https://api.example.com/v1/me{Authorization: Bearer TOKEN}{Accept: application/json})
-EDIT(https://api.example.com/v1/thing/42{Authorization: Bearer TOKEN}{Content-Type: application/json}):{"done":true}:
+Use a web URL as an addressable entry. An unscoped READ performs a GET
+or reuses a fresh stored GET representation, then streams the selected response
+channel. HTML becomes a readable model-facing body (normally markdown); its
+faithful DOM is retained separately. Auxiliary channels are never presented by
+default.
+
+| Operation                         | Remote action | Effect                                                                         |
+| --------------------------------- | ------------- | ------------------------------------------------------------------------------ |
+| Unscoped `READ(http(s)://…)`      | GET           | Acquire/reuse the response and publish the selected channel                    |
+| Scoped `READ(http(s)://…)<scope>` | None          | Read a range from the selected already-materialized channel; never refetch     |
+| `FIND(http(s)://…):matcher`       | GET if needed | Prepare an exact URL, then return standard JSON metadata and match coordinates |
+| `SEND[200](http(s)://…):body:`    | POST          | Submit the body and stream the response                                        |
+| `EDIT(http(s)://…):body:`         | PUT           | Replace the whole remote resource; do not use a line scope                     |
+| `KILL(http(s)://…)`               | DELETE        | Delete the remote resource and stream the response                             |
+
+A path-pattern FIND searches only web entries already materialized in the
+workspace; a pattern cannot discover the remote web. FIND returns navigation
+metadata, not the selected page body. Use READ for content.
+
+Caller cancellation of an exact acquisition returns `499 cancelled`. The
+independent byte-probe deadline remains an ordinary unavailable result.
+
+| Direct response                      | `body`                                                       | Other channel                              |
+| ------------------------------------ | ------------------------------------------------------------ | ------------------------------------------ |
+| GET HTML                             | Readable projection of the rendered page                     | Faithful rendered DOM in `#html`           |
+| GET `text/event-stream`              | Event `data` chunks after READ `102`                          | Initial response in `#header`              |
+| Configured textual response          | Incremental UTF-8 text under its declared type               | Status and headers in `#header`            |
+| Binary with a readable projection    | Derived Unicode under the projection output type             | Origin type and projection ID in `#header` |
+| Binary without a readable projection | Empty marker under its type or `application/octet-stream`    | Status and headers in `#header`            |
+
+Projection presence is structural: a returned projection is accepted even
+when its content is empty. `422 no-readable-projection` means exact acquisition,
+or a direct HTML READ, produced no model-facing body. A direct HTML READ retains
+its faithful `#html` and `#header` evidence; exact FIND preparation creates no entry.
+An internal projection exception instead returns non-retryable
+`500 projection-failed`; a browser failure returns retryable
+`502 render-failed`.
+
+A binary response uses the installed mimetype reader when one supplies a
+bounded Unicode projection; raw bytes never enter a durable channel. Without a
+reader, a direct operation returns `415 binary-response-unsupported`. Input
+above the configured byte ceiling returns `413 projection-input-limit`. The
+remote response was received and its metadata remains in `#header`; do not
+retry a POST, PUT, or DELETE solely to retrieve its binary body. Exact FIND
+instead prunes responses that produce no readable projection.
+
+`#header` contains the remote HTTP status line and headers. The PLURNK
+operation result describes the streaming lifecycle; `SEND[code]` is never the
+remote HTTP status. An HTTP 4xx/5xx response still streams normally and remains
+visible in `#header`.
+
+For SSE, the response and persisted `#header` establish acquisition. READ then
+returns `102` while events continue. Origin close settles the subscription at
+`200`; later cancellation or transfer failure settles it at `499` or `502`
+without rewriting the initial READ.
+
+Re-reading without a scope can reuse only a complete GET acquired without
+explicit request metadata whose response had no `Vary` field. Plurnk keeps one
+representation per URL, so any target metadata or `Vary` response bypasses both
+the freshness shortcut and old validators instead of creating a variant store.
+Eligible content is served directly only while both the operator TTL and any
+origin `max-age` or `Expires` lifetime remain live. `no-cache` requires origin
+validation; `no-store` evidence remains in the log but supplies neither content
+nor validators to a later request. Only singular, syntactically valid stored
+validators are sent. A 304 restores the stored channels only when its ETag or
+Last-Modified value identifies the nominated representation; otherwise
+acquisition fails without serving the stored body. A valid 304 updates cache
+and validator metadata while preserving fields that describe the
+already-processed body. Responses to POST, PUT, and DELETE are not reused as
+later GET representations. A projected GET is reused only while the installed
+reader has the same projection identity; changing it forces a full acquisition
+without old validators.
+
+A scoped READ never fetches. Its fragment, or `body` by default, selects an
+already-materialized channel before the universal READ contract applies the
+range. If that channel is absent, READ the URL without a scope to acquire the
+response first.
+
+Request headers ride inside the target as ordered trailing `{Key: value}`
+blocks, one header per block:
+
+```plurnk
+<<READ(https://api.example.com/v1/me{Authorization: Bearer TOKEN}{Accept: application/json})::READ
+<<EDIT(https://api.example.com/v1/thing/42{Authorization: Bearer TOKEN}{Content-Type: application/json}):{"done":true}:EDIT
 ```
 
-Percent-encode `)`, `<`, and `}` inside a header value (the path-encoding rule).
-
-Host handling: a GitHub `…/blob/…` URL is fetched as its `raw.githubusercontent.com`
-source (line-navigable, exact) rather than the JS code-viewer page — so
-`READ(https://github.com/owner/repo/blob/main/src/x.ts)` returns the file's source.
-
-Cancel / cache:
-
-- `SEND[499](http(s)://…)` — cancel an in-flight request (abort the fetch).
-- `SEND[410](http(s)://…)` — drop the locally cached copy, forcing the next READ
-  to full-fetch instead of revalidate. A local cache drop, **not** an HTTP
-  DELETE — use `KILL` to DELETE the remote resource.
+Percent-encode `)`, `<`, and `}` inside a header value.
+An exact FIND forwards these headers when it must acquire the URL, but the
+result remains intentionally ineligible for later cache reuse.
 
-The `SEND[code]` is loop disposition (`102`/`200`/…), never the HTTP status —
-the real `2xx`/`4xx` comes back in `#header`.
+GET acquisition of a GitHub `…/blob/…` URL uses its
+`raw.githubusercontent.com` source. The addressed GitHub URL remains entry
+identity. POST, PUT, and DELETE never use that rewrite.
 
-Status: `102` streaming · `499` cancelled · `502` upstream/render failure.
+| Control                  | Effect                                                                |
+| ------------------------ | --------------------------------------------------------------------- |
+| `SEND[499](http(s)://…)` | Cancel the routed in-flight acquisition                               |
+| `SEND[410](http(s)://…)` | Delete the local stored response; the next READ must acquire it again |
 
-For a persistent, bidirectional connection, see the `wss://` scheme.
+For a persistent bidirectional connection, use `wss://`.

package/docs/wss.md

@@ -1,45 +1,41 @@
 # wss:// — WebSocket
 
-A full-duplex, persistent connection to a WebSocket origin. Unlike `http://`
-(request/response) or SSE (a one-way `http://` event stream), a WebSocket is
-**bidirectional and stateful**: you open it once, then send and receive on the
-same live connection until it closes.
-
-## Ops
-
-| Op | Effect |
-| --- | --- |
-| `READ(wss://host/path)` | Open the socket. Inbound frames stream into the `messages` channel as they arrive; the READ holds until the socket closes. |
-| `SEND[200](wss://host/path):your message:` | Push a message onto the **already-open** socket. READ it first — a SEND with no open socket is a `409`. |
-| `SEND[499](wss://host/path)` | Cancel: closes the open socket. |
-| `KILL(wss://host/path)` | Close the open socket. |
-
-```
-<<READ(wss://echo.websocket.events)::READ
-<<SEND[200](wss://echo.websocket.events):hello:SEND
-<<KILL(wss://echo.websocket.events)::KILL
-```
-
-A READ returns `102 Processing` and the socket's inbound frames accumulate in the
-`messages` channel across turns — read them as they land, the way you read any
-streaming subscription. The connection stays open for concurrent `SEND`s until
-you `KILL` it or the origin closes.
-
-## Model
-
-- **One socket per target, per workspace.** The connection a READ opens is keyed by
-  its path; a later SEND/KILL to the same target acts on that connection.
-- **SSRF-guarded.** The target is resolved and checked before connecting — a
-  `ws://`/`wss://` into loopback, link-local, or RFC-1918/CGNAT space is refused
-  (`403`), the same guard the fetch path uses.
-
-## Day-one limits
-
-- **Text frames only.** Binary frames stringify loosely; structured binary is a
-  follow-up (#468).
-- **No reconnection.** A dropped socket closes the READ; re-READ to reopen.
-- **Default handshake identity.** Custom request headers on the WebSocket
-  handshake aren't wired yet (the standard `WebSocket` constructor has no header
-  slot); pending, tracked on #468.
-
-Runtime: Node ≥22 (global `WebSocket`).
+Use WebSocket for a persistent, bidirectional connection. `wss` is a
+stateful scheme, not an HTTP content type: READ claims a workspace address and
+owns its socket until terminal settlement, while concurrent SEND and KILL
+operations address that owner.
+
+| Operation                             | Effect                                                                                     |
+| ------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `READ(wss://host/path)`               | Claim the address, connect, mark `messages` active on `open`, and stream inbound frames    |
+| A second `READ` of the same address   | Return `409` until the existing owner's terminal cleanup releases the claim                |
+| `SEND[200](wss://host/path):message:` | Send only through an open socket; claimed, connecting, or settling owners return `409`     |
+| `SEND[499](wss://host/path)`          | Cancel the owning READ through its routed subscription handle                              |
+| `KILL(wss://host/path)`               | Close or cancel the claimed owner; an address with no owner is `404`                       |
+
+| Owner state  | Meaning                                              | `SEND[200]`                                      |
+| ------------ | ---------------------------------------------------- | ------------------------------------------------ |
+| `claimed`    | Address reserved while entry/subscription setup runs | `409`; no second ownership path is created       |
+| `connecting` | Native socket exists but has not emitted `open`      | `409`; wait for the active stream event          |
+| `open`       | `open` was observed and the native state is open     | Sends the message                                |
+| `settling`   | A terminal transition owns cleanup                   | `409`; wait for cleanup before another READ      |
+
+The native `open` event plus durable `messages` activation is the acquisition
+boundary. It emits the ordinary metadata-only stream event and returns the READ
+at `102`; later operations from the same worker or client may then SEND or KILL
+the live owner. A close before acquisition is a direct `502` connection
+failure. After acquisition, close, cancellation, and failure settle the retained
+subscription without rewriting the initial READ.
+
+Connection identity includes the workspace, exact `ws`/`wss` protocol, host,
+non-default port, path, and ordered query. A fragment does not change socket
+identity; `messages` is the only current channel.
+
+| Current transport boundary | Behavior                                                                |
+| -------------------------- | ----------------------------------------------------------------------- |
+| Inbound payload            | String event data only; no coercion or binary projection                |
+| Inbound order              | Native event order; one durable write completes before the next begins  |
+| Binary inbound payload     | Keep the text prefix, prune the suffix, settle `415`, and close `1003`   |
+| Persistence failure        | Keep the successful prefix; prune queued and later frames; settle `500` |
+| Reconnection               | None; READ again after terminal cleanup                                 |
+| Handshake headers          | Target header metadata is not applied                                   |

package/package.json

@@ -1,21 +1,25 @@
 {
     "name": "@plurnk/plurnk-schemes-http",
-    "version": "1.3.12",
-    "description": "http(s):// URI scheme handler for the plurnk agent runtime — fetch + streaming response body.",
+    "version": "1.4.0",
+    "description": "HTTP(S) request/response and WebSocket scheme handlers for the plurnk agent runtime.",
     "keywords": [
         "plurnk",
         "scheme",
         "uri",
         "http",
-        "https"
+        "https",
+        "websocket",
+        "ws",
+        "wss"
     ],
-    "homepage": "https://github.com/plurnk/plurnk-schemes-http#readme",
+    "homepage": "https://github.com/plurnk/plurnk-service/tree/main/plurnk-schemes-http#readme",
     "bugs": {
-        "url": "https://github.com/plurnk/plurnk-schemes-http/issues"
+        "url": "https://repo.possumtech.com/plurnk/plurnk-service/issues"
     },
     "repository": {
         "type": "git",
-        "url": "git+https://github.com/plurnk/plurnk-schemes-http.git"
+        "url": "git+https://github.com/plurnk/plurnk-service.git",
+        "directory": "plurnk-schemes-http"
     },
     "engines": {
         "node": ">=26"
@@ -49,7 +53,6 @@
     },
     "files": [
         "dist/**/*",
-        "scripts/**/*",
         ".env.defaults",
         "docs/**/*",
         "README.md",
@@ -60,17 +63,17 @@
         "test:unit": "node --conditions=plurnk-dev --test --env-file=.env.defaults src/**/*.test.ts",
         "test:intg": "node --conditions=plurnk-dev --test --env-file=.env.defaults test/integration/**/*.test.ts",
         "test": "npm run test:lint && npm run test:unit",
+        "build:clean": "rm -rf dist",
         "build:dist": "tsc -p tsconfig.build.json",
-        "build": "npm run build:dist",
-        "postinstall": "node scripts/install-browser.mjs",
+        "build": "npm run build:clean && npm run build:dist",
         "prepublishOnly": "npm audit --audit-level=moderate && npm test",
         "prepack": "npm run build"
     },
     "peerDependencies": {
-        "@plurnk/plurnk-schemes": "^1.3.12"
+        "@plurnk/plurnk-schemes": "^1.4.0"
     },
     "dependencies": {
         "eventsource-parser": "^3.1.0",
-        "playwright": "1.62.0"
+        "playwright": "1.62.1"
     }
 }

package/scripts/install-browser.mjs

@@ -1,19 +0,0 @@
-import { spawnSync } from "node:child_process";
-import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const skipped = /^(1|true|yes)$/i.test(process.env.PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD ?? "");
-if (skipped) {
-    console.info("plurnk-schemes-http: browser download skipped by PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD");
-    process.exit(0);
-}
-
-const playwrightEntry = fileURLToPath(import.meta.resolve("playwright"));
-const cli = resolve(dirname(playwrightEntry), "cli.js");
-const env = {
-    ...process.env,
-    PLAYWRIGHT_BROWSERS_PATH: process.env.PLAYWRIGHT_BROWSERS_PATH ?? "0",
-};
-const result = spawnSync(process.execPath, [cli, "install", "chromium"], { stdio: "inherit", env });
-if (result.error) throw result.error;
-process.exit(result.status ?? 1);