@snap-rail/protocol 0.1.1 → 0.1.3

package/lib/index.js

@@ -1,6 +1,50 @@
 import { defineContract, method } from "./contract.js";
 import { RpcBusinessError, RpcId, err, isRpcError, ok } from "./rpc.js";
 import { z } from "zod";
+//#region lib/types/surfaces.js
+/**
+* The surface vocabulary: one renderer window role. `main` is the operator
+* window (the app's only always-present surface); `ball` is the auxiliary
+* always-on-top surface a plugin drives through the Shell seam — the floating
+* ball.
+*
+* A surface is an identity, not a layout. Every surface boots the same
+* renderer with its own client entry (`snapRail.client.surfaces`) and its own
+* seed set; a plugin face binds to exactly one surface and reads
+* `ctx.client.surface` to know which. Auxiliary surfaces never subscribe to
+* equipment points directly — they consume host-aggregated frames, because a
+* hidden surface must not keep a data path alive and a shown one must not
+* need a second subscription graph.
+*
+* The whitelist is closed on purpose: a plugin may not name an arbitrary URL
+* or spawn an arbitrary window — the Shell owns every window and only these
+* two roles exist.
+*
+* @module @snap-rail/protocol/surfaces
+*/
+/** Every surface id, in boot order (`main` first). */
+const SURFACE_IDS = ["main", "ball"];
+/** The always-on-top auxiliary surfaces: windows the Shell creates lazily. */
+const AUX_SURFACE_IDS = ["ball"];
+/**
+* Whether a wire value names a surface.
+*
+* @param value - the candidate (any wire value).
+* @returns true when the value is a {@link SurfaceId}.
+*/
+function isSurfaceId(value) {
+	return typeof value === "string" && SURFACE_IDS.includes(value);
+}
+/**
+* Whether a wire value names an auxiliary surface.
+*
+* @param value - the candidate (any wire value).
+* @returns true when the value is an {@link AuxSurfaceId}.
+*/
+function isAuxSurfaceId(value) {
+	return typeof value === "string" && AUX_SURFACE_IDS.includes(value);
+}
+//#endregion
 //#region lib/types/schemas.js
 /**
 * Envelope validation at the trust boundary: the type/rpcId/method
@@ -135,4 +179,4 @@ var InProcessApiClient = class extends AbstractApiClient {
 	}
 };
 //#endregion
-export { AbstractApiClient, InProcessApiClient, RpcBusinessError, RpcId, RpcTransportError, defineContract, err, isRpcError, method, ok, parseClientRequest, parseServerRequest };
+export { AUX_SURFACE_IDS, AbstractApiClient, InProcessApiClient, RpcBusinessError, RpcId, RpcTransportError, SURFACE_IDS, defineContract, err, isAuxSurfaceId, isRpcError, isSurfaceId, method, ok, parseClientRequest, parseServerRequest };

package/lib/types/index.d.ts

@@ -7,6 +7,7 @@
  */
 export * from './rpc.ts';
 export * from './methods.ts';
+export * from './surfaces.ts';
 export * from './frames.ts';
 export * from './contract.ts';
 export * from './schemas.ts';

package/lib/types/index.js

@@ -7,6 +7,7 @@
  */
 export * from "./rpc.js";
 export * from "./methods.js";
+export * from "./surfaces.js";
 export * from "./frames.js";
 export * from "./contract.js";
 export * from "./schemas.js";

package/lib/types/surfaces.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The surface vocabulary: one renderer window role. `main` is the operator
+ * window (the app's only always-present surface); `ball` is the auxiliary
+ * always-on-top surface a plugin drives through the Shell seam — the floating
+ * ball.
+ *
+ * A surface is an identity, not a layout. Every surface boots the same
+ * renderer with its own client entry (`snapRail.client.surfaces`) and its own
+ * seed set; a plugin face binds to exactly one surface and reads
+ * `ctx.client.surface` to know which. Auxiliary surfaces never subscribe to
+ * equipment points directly — they consume host-aggregated frames, because a
+ * hidden surface must not keep a data path alive and a shown one must not
+ * need a second subscription graph.
+ *
+ * The whitelist is closed on purpose: a plugin may not name an arbitrary URL
+ * or spawn an arbitrary window — the Shell owns every window and only these
+ * two roles exist.
+ *
+ * @module @snap-rail/protocol/surfaces
+ */
+/** Every surface id, in boot order (`main` first). */
+export declare const SURFACE_IDS: readonly ["main", "ball"];
+/** The always-on-top auxiliary surfaces: windows the Shell creates lazily. */
+export declare const AUX_SURFACE_IDS: readonly ["ball"];
+/** One renderer window role. */
+export type SurfaceId = (typeof SURFACE_IDS)[number];
+/** One auxiliary surface role. */
+export type AuxSurfaceId = (typeof AUX_SURFACE_IDS)[number];
+/**
+ * Whether a wire value names a surface.
+ *
+ * @param value - the candidate (any wire value).
+ * @returns true when the value is a {@link SurfaceId}.
+ */
+export declare function isSurfaceId(value: unknown): value is SurfaceId;
+/**
+ * Whether a wire value names an auxiliary surface.
+ *
+ * @param value - the candidate (any wire value).
+ * @returns true when the value is an {@link AuxSurfaceId}.
+ */
+export declare function isAuxSurfaceId(value: unknown): value is AuxSurfaceId;
+//# sourceMappingURL=surfaces.d.ts.map

package/lib/types/surfaces.js

@@ -0,0 +1,43 @@
+/**
+ * The surface vocabulary: one renderer window role. `main` is the operator
+ * window (the app's only always-present surface); `ball` is the auxiliary
+ * always-on-top surface a plugin drives through the Shell seam — the floating
+ * ball.
+ *
+ * A surface is an identity, not a layout. Every surface boots the same
+ * renderer with its own client entry (`snapRail.client.surfaces`) and its own
+ * seed set; a plugin face binds to exactly one surface and reads
+ * `ctx.client.surface` to know which. Auxiliary surfaces never subscribe to
+ * equipment points directly — they consume host-aggregated frames, because a
+ * hidden surface must not keep a data path alive and a shown one must not
+ * need a second subscription graph.
+ *
+ * The whitelist is closed on purpose: a plugin may not name an arbitrary URL
+ * or spawn an arbitrary window — the Shell owns every window and only these
+ * two roles exist.
+ *
+ * @module @snap-rail/protocol/surfaces
+ */
+/** Every surface id, in boot order (`main` first). */
+export const SURFACE_IDS = ['main', 'ball'];
+/** The always-on-top auxiliary surfaces: windows the Shell creates lazily. */
+export const AUX_SURFACE_IDS = ['ball'];
+/**
+ * Whether a wire value names a surface.
+ *
+ * @param value - the candidate (any wire value).
+ * @returns true when the value is a {@link SurfaceId}.
+ */
+export function isSurfaceId(value) {
+    return typeof value === 'string' && SURFACE_IDS.includes(value);
+}
+/**
+ * Whether a wire value names an auxiliary surface.
+ *
+ * @param value - the candidate (any wire value).
+ * @returns true when the value is an {@link AuxSurfaceId}.
+ */
+export function isAuxSurfaceId(value) {
+    return typeof value === 'string' && AUX_SURFACE_IDS.includes(value);
+}
+//# sourceMappingURL=surfaces.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@snap-rail/protocol",
   "description": "Channel-independent four-quadrant RPC contract between host and clients",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",