spacewave 0.0.0 → 0.57.6

package/examples/task-board/style.css

@@ -0,0 +1,154 @@
+/* Page layout and typography. */
+:root {
+  color-scheme: light;
+  font-family: system-ui, sans-serif;
+  color: #18282d;
+  background: #f3f6f4;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+}
+
+main {
+  width: min(720px, 100%);
+  padding: 36px 24px;
+  margin: 4vh auto;
+}
+
+nav {
+  display: flex;
+  gap: 18px;
+  margin-bottom: 32px;
+}
+
+a {
+  color: #285f4d;
+  text-underline-offset: 4px;
+}
+
+h1 {
+  font-size: clamp(2rem, 6vw, 3rem);
+  line-height: 1.1;
+  margin-bottom: 12px;
+  letter-spacing: -0.04em;
+}
+
+p {
+  line-height: 1.6;
+  color: #4c6065;
+}
+
+.status {
+  display: inline-block;
+  font-size: 0.85rem;
+  background: #dcebe2;
+  padding: 5px 12px;
+  border-radius: 24px;
+}
+
+/* Input controls and their interaction states. */
+form {
+  display: flex;
+  gap: 10px;
+  align-items: end;
+  margin: 30px 0;
+}
+
+label {
+  flex: 1;
+  font-size: 0.9rem;
+  font-weight: 600;
+}
+
+input {
+  display: block;
+  width: 100%;
+  font: inherit;
+  margin-top: 8px;
+  padding: 12px;
+  border: 1px solid #a2b7ad;
+  border-radius: 8px;
+  background: white;
+}
+
+button,
+.button {
+  font: inherit;
+  color: white;
+  background: #285f4d;
+  padding: 12px 16px;
+  border: 0;
+  border-radius: 8px;
+  cursor: pointer;
+}
+
+button:disabled {
+  opacity: 0.55;
+  cursor: default;
+}
+
+:focus-visible {
+  outline: 3px solid #2b7dbe;
+  outline-offset: 3px;
+}
+
+/* Accepted task rows and write feedback. */
+.tasks {
+  list-style: none;
+  padding: 0;
+  border-top: 1px solid #cddbd3;
+}
+
+.task {
+  display: flex;
+  gap: 16px;
+  justify-content: space-between;
+  align-items: center;
+  padding: 18px 0;
+  border-bottom: 1px solid #cddbd3;
+}
+
+.task span {
+  overflow-wrap: anywhere;
+}
+
+.task[data-done='true'] span {
+  text-decoration: line-through;
+  color: #63756b;
+}
+
+.notice {
+  padding: 16px;
+  background: #fff0d2;
+  border-radius: 8px;
+  overflow-wrap: anywhere;
+}
+
+.notice button {
+  margin-top: 10px;
+}
+
+/* Keep the form usable on narrow screens. */
+@media (max-width: 460px) {
+  main {
+    padding: 24px 16px;
+    margin-top: 0;
+  }
+
+  form {
+    flex-wrap: wrap;
+  }
+
+  form label {
+    flex-basis: 100%;
+  }
+
+  form button {
+    width: 100%;
+  }
+}

package/examples/task-board/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2024",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "skipLibCheck": true,
+    "types": ["node", "react"],
+    "lib": ["ES2024", "DOM", "ESNext.Disposable"]
+  },
+  "include": ["*.ts", "*.tsx"]
+}

package/examples/task-board/vanilla.html

@@ -0,0 +1,17 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1" />
+    <title>Task board · Spacewave</title>
+    <link rel="stylesheet" href="/style.css" />
+  </head>
+
+  <body>
+    <main id="app">
+      <p role="status">Connecting…</p>
+    </main>
+
+    <script type="module" src="/vanilla.js"></script>
+  </body>
+</html>

package/examples/task-board/vanilla.ts

@@ -0,0 +1,190 @@
+import { connect, SyncError } from 'spacewave'
+
+import { schema } from './schema.ts'
+
+// Keep the fixed page scaffold separate from task values rendered with textContent.
+const app = document.querySelector<HTMLElement>('#app')!
+app.innerHTML = `
+  <nav>
+    <a href="/">Vanilla</a>
+    <a href="/react">React</a>
+  </nav>
+
+  <h1>Task board</h1>
+  <p>Open two tabs. Add or complete a task and watch both boards update.</p>
+  <div class="status" role="status">Connecting…</div>
+
+  <form>
+    <label>
+      Add a task
+      <input name="title" required maxlength="120" autocomplete="off">
+    </label>
+    <button class="button">Add task</button>
+  </form>
+
+  <div class="notice" role="alert" hidden></div>
+  <p id="freshness" role="status"></p>
+  <ul class="tasks"></ul>
+`
+
+// Bind the controls used by connection, write, and subscription callbacks.
+const form = app.querySelector<HTMLFormElement>('form')!
+const input = app.querySelector<HTMLInputElement>('input')!
+const status = app.querySelector<HTMLElement>('.status')!
+const notice = app.querySelector<HTMLElement>('.notice')!
+const freshness = app.querySelector<HTMLElement>('#freshness')!
+const list = app.querySelector<HTMLElement>('.tasks')!
+
+// Pending form work stays separate from the accepted collection snapshot.
+let pending = false
+let ready = false
+
+/** updateButtons permits edits only while connected and without a pending write. */
+function updateButtons(): void {
+  for (const button of app.querySelectorAll<HTMLButtonElement>('button')) {
+    button.disabled = pending || !ready || button.dataset.done === 'true'
+  }
+}
+
+/** runWrite retains the original write closure so Retry preserves its input and ID. */
+async function runWrite(write: () => Promise<unknown>): Promise<void> {
+  // Suspend edits while the server decides this write's result.
+  pending = true
+  notice.hidden = true
+  updateButtons()
+
+  // Show failures without changing the accepted task rows.
+  try {
+    await write()
+  } catch (error) {
+    notice.hidden = false
+    notice.replaceChildren(
+      document.createTextNode(
+        error instanceof Error
+          ? error.message
+          : 'The change could not complete',
+      ),
+    )
+
+    // Retrying an uncertain write reuses its original input and request ID.
+    if (error instanceof SyncError && error.code === 'UNCERTAIN') {
+      notice.append(document.createTextNode(` Request: ${error.requestId}. `))
+      const retry = document.createElement('button')
+      retry.textContent = 'Retry'
+      retry.onclick = () => {
+        void runWrite(write)
+      }
+      notice.append(retry)
+    }
+  } finally {
+    pending = false
+    updateButtons()
+  }
+}
+
+/** start connects the board and releases its subscriptions when the page leaves. */
+async function start(): Promise<void> {
+  // Open one connection for the page and use its typed task collection.
+  const url = new URL('/sync', location.href)
+  url.protocol = location.protocol === 'https:' ? 'wss:' : 'ws:'
+  const db = await connect({
+    url: url.href,
+    schema,
+    getAccessToken: () => 'local-demo',
+  })
+  const todos = db.collection('todos')
+
+  // Keep connection feedback and edit availability in sync.
+  const stopConnection = db.connection.subscribe((connection) => {
+    ready = connection.status === 'ready'
+    status.textContent =
+      connection.status === 'ready'
+        ? 'Connected'
+        : connection.status === 'reconnecting'
+          ? 'Reconnecting…'
+          : 'Connection closed'
+    updateButtons()
+  })
+
+  // Replace the rendered list with each complete server snapshot.
+  const stop = todos.subscribe(
+    {},
+    {
+      next: (state) => {
+        // Describe freshness separately from the retained task values.
+        freshness.textContent =
+          state.status === 'loading'
+            ? 'Loading tasks…'
+            : state.status === 'stale'
+              ? 'Showing the last saved view while reconnecting…'
+              : state.status === 'error'
+                ? (state.error?.message ?? 'Tasks could not load')
+                : state.data.length
+                  ? 'All changes saved'
+                  : 'No tasks yet'
+
+        // Render task titles as text and wire each row's completion action.
+        list.replaceChildren(
+          ...state.data.map(({ key, value }) => {
+            // Build the row from the accepted task value.
+            const row = document.createElement('li')
+            row.className = 'task'
+            row.dataset.done = String(value.done)
+            const title = document.createElement('span')
+            title.textContent = value.title
+
+            // Keep a completion request's ID stable if the user retries it.
+            const complete = document.createElement('button')
+            complete.textContent = value.done ? 'Completed' : 'Complete'
+            complete.dataset.done = String(value.done)
+            complete.onclick = () => {
+              const requestId = crypto.randomUUID()
+              void runWrite(() =>
+                db.mutate('completeTodo', { id: key }, { requestId }),
+              )
+            }
+            row.append(title, complete)
+            return row
+          }),
+        )
+        updateButtons()
+      },
+    },
+  )
+
+  // Capture a new task's input once so recovery can repeat the exact write.
+  form.onsubmit = (event) => {
+    // Accept a nonempty title only when edits are available.
+    event.preventDefault()
+    const title = input.value.trim()
+    if (!title || pending || !ready) return
+
+    // Clear the input after acceptance, preserving the IDs inside the closure.
+    const key = crypto.randomUUID()
+    const requestId = crypto.randomUUID()
+    void runWrite(async () => {
+      await todos.put(key, { title, done: false }, { requestId })
+      input.value = ''
+    })
+  }
+
+  // Release both subscriptions before closing the page's database.
+  window.addEventListener(
+    'pagehide',
+    () => {
+      stop()
+      stopConnection()
+      void db.close()
+    },
+    { once: true },
+  )
+}
+
+// Disable edits until admission succeeds and make startup failures visible.
+updateButtons()
+void start().catch((error: unknown) => {
+  status.textContent = 'Connection failed'
+  notice.hidden = false
+  notice.textContent =
+    error instanceof Error ? error.message : 'The board could not connect'
+})

package/package.json

@@ -1,22 +1,60 @@
 {
   "name": "spacewave",
-  "description": "Cross-platform communications daemon and library.",
-  "version": "0.0.0",
-  "license": "Apache-2.0",
-  "author": {
-    "name": "Aperture Robotics LLC.",
-    "email": "support@aperture.us",
-    "url": "http://aperture.us"
+  "version": "0.57.6",
+  "description": "Typed live collections backed by a durable Spacewave World",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/s4wave/spacewave.git",
+    "directory": "packages/spacewave"
+  },
+  "homepage": "https://github.com/s4wave/spacewave/tree/master/packages/spacewave#readme",
+  "bugs": "https://github.com/s4wave/spacewave/issues",
+  "type": "module",
+  "engines": {
+    "node": ">=24.15.0 <25"
   },
-  "contributors": [
-    {
-      "name": "Christian Stewart",
-      "email": "christian@aperture.us",
-      "url": "http://github.com/paralin"
+  "exports": {
+    ".": {
+      "types": "./dist/types/packages/spacewave/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./server": {
+      "types": "./dist/types/packages/spacewave/server.d.ts",
+      "import": "./dist/server.mjs"
+    },
+    "./react": {
+      "types": "./dist/types/packages/spacewave/react.d.ts",
+      "import": "./dist/react.mjs"
     }
-  ],
-  "repository": {
-    "url": "git+ssh://git@github.com/aperturerobotics/spacewave/net.git"
   },
-  "type": "module"
+  "types": "./dist/types/packages/spacewave/index.d.ts",
+  "dependencies": {
+    "@standard-schema/spec": "^1.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=19.2.0 <20",
+    "@types/react": ">=19.2.0 <20",
+    "@types/node": ">=24 <25"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "@types/react": {
+      "optional": true
+    },
+    "@types/node": {
+      "optional": true
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "examples",
+    "API.md",
+    "AGENTS.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "license": "Apache-2.0"
 }