@theruntime/protocol 0.0.0 → 0.0.1

package/src/readiness.ts

@@ -0,0 +1,52 @@
+import { asRecord, optionalNonNegativeInteger } from "./operations/parse-helpers";
+
+const NOUN = "a route readiness";
+
+/**
+ * What a route's page has reported about its own rendering. "unknown" is no document served yet.
+ * "pending" is a document served and no report yet, inside the window. "ready" is a first frame
+ * committed with children under the root. "empty" is a first frame committed with none.
+ * "silent" is a document served and nothing reported, past the window.
+ */
+export const APP_READINESS_STATES = ["unknown", "pending", "ready", "empty", "silent"] as const;
+export type AppReadinessState = (typeof APP_READINESS_STATES)[number];
+
+/**
+ * How long a served document may report nothing before the reading calls it silent. Sized above
+ * the slowest cold boot the engine has been measured through, so silent never names a load that
+ * is merely slow. A caller with a tighter budget reads sinceMs and decides for itself.
+ */
+export const APP_READY_WINDOW_MS = 120_000;
+
+export function isAppReadinessState(value: unknown): value is AppReadinessState {
+  if (typeof value !== "string") return false;
+  const states: readonly string[] = APP_READINESS_STATES;
+  return states.includes(value);
+}
+
+export interface AppReadiness {
+  readonly state: AppReadinessState;
+  /** Milliseconds since the stamp the state is derived from. Absent for "unknown". */
+  readonly sinceMs?: number;
+  /** How many elements the root held when the first frame committed. Present once a report
+   * arrived, including the zero that names a page that mounted and drew nothing. */
+  readonly rootChildren?: number;
+}
+
+export function parseAppReadiness(value: unknown): AppReadiness {
+  const record = asRecord(value, NOUN);
+  if (!isAppReadinessState(record.state)) {
+    throw new Error(`${NOUN} names a state of: ${APP_READINESS_STATES.join(", ")}`);
+  }
+  const sinceMs = optionalNonNegativeInteger(record, "sinceMs", NOUN);
+  const rootChildren = optionalNonNegativeInteger(record, "rootChildren", NOUN);
+  return {
+    state: record.state,
+    ...(sinceMs !== undefined ? { sinceMs } : {}),
+    ...(rootChildren !== undefined ? { rootChildren } : {}),
+  };
+}
+
+export function serializeAppReadiness(readiness: AppReadiness): string {
+  return JSON.stringify(readiness);
+}

package/src/records/index.ts

@@ -0,0 +1,46 @@
+/** The record surface, re-exported by the package barrel as one line. */
+export { RECORD_STATUSES, isRecordStatus } from "../operations/record-status";
+export type { RecordStatus } from "../operations/record-status";
+
+export { parseAppRecord } from "../operations/app-record";
+export type { AppRecord } from "../operations/app-record";
+
+export {
+  parseListRecordsInput,
+  serializeListRecordsInput,
+  parseListRecordsResult,
+  serializeListRecordsResult,
+} from "../operations/list-records";
+export type { ListRecordsInput, ListRecordsResult } from "../operations/list-records";
+
+export {
+  parseGetRecordInput,
+  serializeGetRecordInput,
+  parseGetRecordResult,
+  serializeGetRecordResult,
+} from "../operations/get-record";
+export type { GetRecordInput, GetRecordResult } from "../operations/get-record";
+
+export {
+  parseSetRecordStatusInput,
+  serializeSetRecordStatusInput,
+  parseSetRecordStatusResult,
+  serializeSetRecordStatusResult,
+} from "../operations/set-record-status";
+export type { SetRecordStatusInput, SetRecordStatusResult } from "../operations/set-record-status";
+
+export {
+  parseDeleteRecordInput,
+  serializeDeleteRecordInput,
+  parseDeleteRecordResult,
+  serializeDeleteRecordResult,
+} from "../operations/delete-record";
+export type { DeleteRecordInput, DeleteRecordResult } from "../operations/delete-record";
+
+export {
+  parseSaveRecordInput,
+  serializeSaveRecordInput,
+  parseSaveRecordResult,
+  serializeSaveRecordResult,
+} from "../operations/save-record";
+export type { SaveRecordInput, SaveRecordResult } from "../operations/save-record";

package/src/routes/index.ts

@@ -0,0 +1,104 @@
+/** The route surface, re-exported by the package barrel as one line. */
+export {
+  parseRegisterRouteInput,
+  serializeRegisterRouteInput,
+  parseRegisterRouteResult,
+  serializeRegisterRouteResult,
+} from "../operations/register-route";
+export type { RegisterRouteInput, RegisterRouteResult } from "../operations/register-route";
+
+export {
+  parseUnregisterRouteInput,
+  serializeUnregisterRouteInput,
+  parseUnregisterRouteResult,
+  serializeUnregisterRouteResult,
+} from "../operations/unregister-route";
+export type { UnregisterRouteInput, UnregisterRouteResult } from "../operations/unregister-route";
+
+export {
+  parseListRoutesInput,
+  serializeListRoutesInput,
+  parseListRoutesResult,
+  serializeListRoutesResult,
+} from "../operations/list-routes";
+export type { ListRoutesInput, ListRoutesResult, RouteSummary } from "../operations/list-routes";
+
+export {
+  parseDescribeRouteInput,
+  serializeDescribeRouteInput,
+  parseDescribeRouteResult,
+  serializeDescribeRouteResult,
+} from "../operations/describe-route";
+export type {
+  DescribeRouteInput,
+  DescribeRouteResult,
+  RouteCard,
+} from "../operations/describe-route";
+
+export {
+  parseDeclareRouteInput,
+  serializeDeclareRouteInput,
+  parseDeclareRouteResult,
+  serializeDeclareRouteResult,
+} from "../operations/declare-route";
+export type { DeclareRouteInput, DeclareRouteResult } from "../operations/declare-route";
+
+export {
+  COMPONENT_DECLARATIONS,
+  DECLARATION_FIELDS,
+  HOST_DECLARATIONS,
+  REACT_DECLARATIONS,
+  isComponentDeclaration,
+  isEmptyDeclarationPatch,
+  isHostDeclaration,
+  isReactDeclaration,
+  optionalDeclarationPatch,
+  parseDeclaration,
+  parseDeclarationPatch,
+} from "../operations/declaration";
+export type {
+  ComponentDeclaration,
+  Declaration,
+  DeclarationField,
+  DeclarationPatch,
+  HostDeclaration,
+  ReactDeclaration,
+} from "../operations/declaration";
+
+export {
+  parseArchiveRouteInput,
+  serializeArchiveRouteInput,
+  parseArchiveRouteResult,
+  serializeArchiveRouteResult,
+} from "../operations/archive-route";
+export type { ArchiveRouteInput, ArchiveRouteResult } from "../operations/archive-route";
+
+export {
+  parseDeleteAppInput,
+  serializeDeleteAppInput,
+  parseDeleteAppResult,
+  serializeDeleteAppResult,
+} from "../operations/delete-app";
+export type { DeleteAppInput, DeleteAppResult } from "../operations/delete-app";
+
+export {
+  parseRebootRouteInput,
+  serializeRebootRouteInput,
+  parseRebootRouteResult,
+  serializeRebootRouteResult,
+} from "../operations/reboot-route";
+export type { RebootRouteInput, RebootRouteResult } from "../operations/reboot-route";
+
+export { VISIBILITIES, isVisibility } from "../operations/visibility";
+export type { Visibility } from "../operations/visibility";
+
+export {
+  parseSetRouteVisibilityInput,
+  serializeSetRouteVisibilityInput,
+  parseSetRouteVisibilityResult,
+  serializeSetRouteVisibilityResult,
+} from "../operations/set-route-visibility";
+export type {
+  SetRouteVisibilityInput,
+  SetRouteVisibilityResult,
+} from "../operations/set-route-visibility";

package/src/selection/index.ts

@@ -0,0 +1,16 @@
+/** The selection surface, re-exported by the package barrel as one line. */
+export {
+  parseSetSelectionInput,
+  serializeSetSelectionInput,
+  parseSetSelectionResult,
+  serializeSetSelectionResult,
+} from "../operations/set-selection";
+export type { SetSelectionInput, SetSelectionResult } from "../operations/set-selection";
+
+export {
+  parseQuerySelectionInput,
+  serializeQuerySelectionInput,
+  parseQuerySelectionResult,
+  serializeQuerySelectionResult,
+} from "../operations/query-selection";
+export type { QuerySelectionInput, QuerySelectionResult } from "../operations/query-selection";

package/src/sessions/index.ts

@@ -0,0 +1,24 @@
+/** The session surface, re-exported by the package barrel as one line. */
+export {
+  IDENTITY_VIAS,
+  parseIdentifyInput,
+  serializeIdentifyInput,
+  parseIdentifyResult,
+  serializeIdentifyResult,
+} from "../operations/identify";
+export type { IdentifyInput, IdentifyResult, IdentityVia } from "../operations/identify";
+
+export { parseHeartbeat, serializeHeartbeat } from "../operations/heartbeat";
+export type { Heartbeat } from "../operations/heartbeat";
+
+export {
+  parseListPresenceInput,
+  serializeListPresenceInput,
+  parseListPresenceResult,
+  serializeListPresenceResult,
+} from "../operations/list-presence";
+export type {
+  ListPresenceInput,
+  ListPresenceResult,
+  PresenceBeatSummary,
+} from "../operations/list-presence";

package/src/snapshots/index.ts

@@ -0,0 +1,20 @@
+/** The snapshot surface, re-exported by the package barrel as one line. */
+export {
+  parseCaptureSnapshotInput,
+  serializeCaptureSnapshotInput,
+  parseCaptureSnapshotResult,
+  serializeCaptureSnapshotResult,
+} from "../operations/capture-snapshot";
+export type { CaptureSnapshotInput, CaptureSnapshotResult } from "../operations/capture-snapshot";
+
+export {
+  parseGetSnapshotInput,
+  serializeGetSnapshotInput,
+  parseGetSnapshotResult,
+  serializeGetSnapshotResult,
+} from "../operations/get-snapshot";
+export type {
+  GetSnapshotInput,
+  GetSnapshotResult,
+  SnapshotState,
+} from "../operations/get-snapshot";

package/src/templates/index.ts

@@ -0,0 +1,14 @@
+/** The template surface, re-exported by the package barrel as one line. */
+export {
+  parseListTemplatesInput,
+  serializeListTemplatesInput,
+  parseListTemplatesResult,
+  serializeListTemplatesResult,
+  parseTemplateSummary,
+  serializeTemplateSummary,
+} from "../operations/list-templates";
+export type {
+  ListTemplatesInput,
+  ListTemplatesResult,
+  TemplateSummary,
+} from "../operations/list-templates";

package/src/toolchain/index.ts

@@ -0,0 +1,36 @@
+/** The toolchain surface, re-exported by the package barrel as one line. */
+export {
+  parseAddPackageInput,
+  serializeAddPackageInput,
+  parseAddPackageResult,
+  serializeAddPackageResult,
+} from "../operations/add-package";
+export type { AddPackageInput, AddPackageResult } from "../operations/add-package";
+
+export {
+  parseListPackagesInput,
+  serializeListPackagesInput,
+  parseListPackagesResult,
+  serializeListPackagesResult,
+} from "../operations/list-packages";
+export type {
+  ListPackagesInput,
+  ListPackagesResult,
+  PackageSource,
+  PackageSummary,
+} from "../operations/list-packages";
+
+export {
+  COMPONENT_SOURCES,
+  isComponentSource,
+  parseAddComponentInput,
+  serializeAddComponentInput,
+  parseAddComponentResult,
+  serializeAddComponentResult,
+} from "../operations/add-component";
+export type {
+  AddComponentInput,
+  AddComponentResult,
+  ComponentSource,
+  LeftImport,
+} from "../operations/add-component";

package/src/version.ts

@@ -0,0 +1,3 @@
+export const PROTOCOL_VERSION = 1;
+
+export type ProtocolVersion = typeof PROTOCOL_VERSION;

package/README.md

@@ -1,3 +0,0 @@
-# @theruntime/protocol
-
-Placeholder. The first release replaces it.