@xpufx/paseo-helper-demo 0.2.0 → 0.2.1

package/README.md

@@ -55,3 +55,24 @@ The modal navbar renders two ways, switchable in the Settings tab (`navigationSt
 - `helper-demo.agent-identity`: active agent identity/session for self-inspection.
 - `helper-demo.beacon-set` / `beacon-blink` / `beacon-clear`: workspace status beacon control.
 - `helper-demo.settings`: persisted settings (`showCpuUsage`, `accentPillLabel`, `pollingRate`, `navigationStyle`, `highCpuThreshold`, flair fields).
+
+## TEMP: upstream server settings handle (issue #62)
+
+A **temporary** sidebar page (`Server Settings (temp)`) demonstrates the
+upstream server-side settings handle added in Paseo `0.9.0-beta.1` (upstream
+PR #4674), *not* our helper's `PluginStorage`/`registerSettingsRpc` layer:
+
+- `index.server.ts` calls `server.registerSettings(defineSettings({ id: "server-demo", ... }))`
+  and keeps the returned `PluginSettings` handle.
+- The daemon reads through `handle.read()` and subscribes through
+  `handle.subscribe()` (see `server/server-settings.ts`).
+- The page (`client/server-settings.tsx`) renders the daemon's handle state
+  (`status` / `revision` / `values` / `subscribe()` event count) and writes the
+  same document through the host's auto-registered `settings.server-demo.*` RPC.
+- The document lives at `~/.paseo/plugin-settings/paseo-helper-demo/server-demo.json`.
+
+On hosts older than `0.9.0-beta.1`, `registerSettings()` returns `void`; the page
+then reports the handle as unavailable and points at the SDK version. This page
+is scaffolding for the #62 demo and is not wired into the pill/modal surfaces.
+
+Tests: `npm test --workspace plugins/demo` (or `npx vitest run` in `plugins/demo`).

package/client/server-settings.tsx

@@ -0,0 +1,350 @@
+import React, { useEffect, useMemo, useState } from "react";
+import { Text } from "react-native";
+import type { PluginSurfaceProps } from "@getpaseo/plugin/client";
+import {
+  Badge,
+  Button,
+  Card,
+  CodeBlock,
+  FormRow,
+  KeyValue,
+  KeyValueGroup,
+  ModalBody,
+  SectionHeader,
+  Stack,
+  StatusDot,
+  TextInput,
+  Toggle,
+  registerSidebarSurface,
+  triggerHaptic,
+  usePluginTheme,
+  type SidebarSurfaceRegistrar,
+} from "paseo-plugin-helper/client";
+import { useRpcQuery, useRpcMutation } from "paseo-plugin-helper/core";
+import {
+  DEMO_SERVER_SETTINGS_EXPECTED_PATH,
+  DEMO_SERVER_SETTINGS_ID,
+  DemoSettingsSchema,
+  demoSettingsRpc,
+  demoSettingsSnapshotContract,
+  type DemoSettingsValues,
+  type ServerSettingsSnapshot,
+} from "../shared/server-settings.js";
+
+/**
+ * TEMP DEMO (issue #62) - not a production surface.
+ *
+ * Shows the upstream server-side settings handle for `id: "server-demo"`:
+ * the daemon's `registerSettings()` returned a `PluginSettings` handle and
+ * reads/subscribes through it. The write path is the host's auto-registered
+ * `settings.server-demo.*` RPC (same document the host `useSettings()` uses),
+ * never our helper `PluginStorage`/`registerSettingsRpc` layer.
+ */
+
+function statusBadge(snapshot: ServerSettingsSnapshot | undefined) {
+  if (!snapshot || snapshot.status === "uninitialized") {
+    return { variant: "warning" as const, label: "Awaiting first read" };
+  }
+  if (snapshot.status === "invalid") {
+    return { variant: "danger" as const, label: "Invalid document" };
+  }
+  return { variant: "success" as const, label: "ready" };
+}
+
+function handleSource(snapshot: ServerSettingsSnapshot | undefined): string {
+  if (!snapshot) return "reading server handle...";
+  if (!snapshot.handleAvailable) return "unavailable (SDK < 0.9.0-beta.1)";
+  if (snapshot.subscribed) return "registerSettings() -> read() + subscribe()";
+  return "registerSettings() -> read() (subscribe inactive)";
+}
+
+export function ServerSettingsDemoSurface(_props: PluginSurfaceProps) {
+  const { colors, typography } = usePluginTheme();
+  const [label, setLabel] = useState<string>("");
+
+  // Snapshot reflects what the DAEMON observed on the handle; each poll issues a
+  // fresh handle.read() server-side (see handleGetServerSettingsSnapshot).
+  const { data, isLoading, refetch, error } = useRpcQuery(
+    demoSettingsSnapshotContract,
+    {},
+    { refetchInterval: 2000 },
+  );
+
+  // The write side of the exact same document, through upstream's host RPC.
+  const readThroughRpc = useRpcQuery(demoSettingsRpc.read, {}, { refetchInterval: 5000 });
+  const { mutate: writeSettings, isPending: isSaving } = useRpcMutation(demoSettingsRpc.write, {
+    onSuccess: () => {
+      triggerHaptic("success");
+      void refetch();
+      void readThroughRpc.refetch();
+    },
+  });
+  const { mutate: resetSettings, isPending: isResetting } = useRpcMutation(demoSettingsRpc.reset, {
+    onSuccess: () => {
+      triggerHaptic("warning");
+      void refetch();
+      void readThroughRpc.refetch();
+    },
+  });
+
+  const rpcRead = readThroughRpc.data;
+  const values: DemoSettingsValues | undefined =
+    rpcRead?.status === "ready" ? DemoSettingsSchema.parse(rpcRead.values) : undefined;
+  const revision = data?.revision ?? rpcRead?.revision ?? "missing";
+
+  useEffect(() => {
+    if (values && label === "") setLabel(String(values.label));
+  }, [values, label]);
+
+  const badge = statusBadge(data);
+  const eventHistory = useMemo(() => {
+    if (!data?.lastEventAt) return "no subscribe() events observed yet";
+    return `${data.eventCount} event(s); last ${data.lastEventAt} (${data.lastEventStatus})`;
+  }, [data]);
+
+  const handleAvailable = data?.handleAvailable ?? false;
+  const controlsDisabled = !handleAvailable || isSaving || isResetting || !values;
+
+  return (
+    <ModalBody
+      headerMode="pinned"
+      refreshing={isLoading}
+      onRefresh={() => {
+        void refetch();
+      }}
+    >
+      <Stack gap={12}>
+        <Card variant="elevated">
+          <Card.Header
+            title="TEMP — Upstream server settings handle (#62)"
+            subtitle="registerSettings() -> read()/subscribe(), read on the daemon process"
+            badge={<Badge label="DEMO" variant="warning" />}
+          />
+
+          <KeyValueGroup columns={2}>
+            <KeyValue
+              label="Settings id"
+              value={data?.settingsId ?? DEMO_SERVER_SETTINGS_ID}
+              copyable
+            />
+            <KeyValue label="Schema version" value={String(data?.schemaVersion ?? 1)} />
+            <KeyValue label="Source" value={handleSource(data)} />
+            <KeyValue
+              label="Handle available"
+              value={handleAvailable ? "yes" : "no"}
+              subValue={
+                handleAvailable
+                  ? "returned by registerSettings()"
+                  : "older host runtime returned void"
+              }
+            />
+          </KeyValueGroup>
+
+          {data?.unavailableReason ? (
+            <Text style={{ color: colors.statusWarning, ...typography.caption }}>
+              {data.unavailableReason}
+            </Text>
+          ) : null}
+        </Card>
+
+        <Card variant="elevated">
+          <Card.Header
+            title="handle.read() snapshot"
+            subtitle="State the daemon process observed, straight from the upstream handle"
+            badge={<Badge label={badge.label} variant={badge.variant} />}
+          />
+          <KeyValueGroup columns={2}>
+            <KeyValue
+              label="Status"
+              value={data?.status ?? "loading"}
+              subValue={data?.error ?? undefined}
+            />
+            <KeyValue
+              label="Revision"
+              value={revision}
+              subValue="sha256 of the stored document"
+              copyable={revision !== "missing"}
+            />
+            <KeyValue label="Daemon read() calls" value={String(data?.readCount ?? 0)} />
+            <KeyValue
+              label="Subscribe active"
+              value={data?.subscribed ? "yes" : "no"}
+              subValue={eventHistory}
+            />
+          </KeyValueGroup>
+
+          <SectionHeader title="Values seen by the server handle" />
+          {data?.values ? (
+            <KeyValueGroup columns={2}>
+              <KeyValue label="label" value={String(data.values.label)} copyable />
+              <KeyValue label="enabled" value={String(data.values.enabled)} />
+              <KeyValue label="threshold" value={String(data.values.threshold)} />
+            </KeyValueGroup>
+          ) : (
+            <Text style={{ color: colors.foregroundMuted, ...typography.caption }}>
+              No ready values yet. The document may not exist on disk until the first write.
+            </Text>
+          )}
+
+          <Text style={{ color: colors.foregroundMuted, ...typography.caption }}>
+            Stored at {data?.expectedPath ?? DEMO_SERVER_SETTINGS_EXPECTED_PATH}
+          </Text>
+        </Card>
+
+        <Card variant="elevated">
+          <Card.Header
+            title="Write path (host settings.<id>.* RPC)"
+            subtitle="Same document, updated through upstream's persisted RPC — then re-read on the daemon"
+          />
+
+          <FormRow
+            label="Label"
+            description="Persisted into the host-scoped document the handle reads"
+          >
+            <TextInput
+              value={label}
+              onChangeText={setLabel}
+              placeholder="upstream handle demo"
+            />
+          </FormRow>
+
+          <FormRow label="Enabled" description="Boolean inside the same document" layout="inline">
+            <Toggle
+              value={Boolean(values?.enabled)}
+              onValueChange={(next) => {
+                triggerHaptic("light");
+                writeSettings({
+                  revision,
+                  values: {
+                    label: values?.label ?? label,
+                    enabled: next,
+                    threshold: values?.threshold ?? 70,
+                  },
+                });
+              }}
+            />
+          </FormRow>
+
+          <FormRow
+            label="Threshold"
+            description={`Integer 0-100 (current: ${values?.threshold ?? "—"})`}
+          >
+            <TextInput
+              value={values ? String(values.threshold) : ""}
+              keyboardType="numeric"
+              onChangeText={(text) => {
+                if (text.trim() === "") return;
+                const threshold = Number.parseInt(text, 10);
+                if (Number.isNaN(threshold)) return;
+                writeSettings({
+                  revision,
+                  values: {
+                    label: values?.label ?? label,
+                    enabled: values?.enabled ?? true,
+                    threshold,
+                  },
+                });
+              }}
+            />
+          </FormRow>
+
+          <Button
+            label={isSaving ? "Saving..." : "Save label to host settings"}
+            variant="primary"
+            size="sm"
+            disabled={controlsDisabled}
+            onPress={() => {
+              triggerHaptic("medium");
+              writeSettings({
+                revision,
+                values: {
+                  label: label.trim() || "upstream handle demo",
+                  enabled: values?.enabled ?? true,
+                  threshold: values?.threshold ?? 70,
+                },
+              });
+            }}
+          />
+
+          <Stack gap={4}>
+            <Text style={{ color: colors.foregroundMuted, ...typography.caption }}>
+              RPC read status: {readThroughRpc.data?.status ?? (readThroughRpc.isLoading ? "loading" : "—")}
+              {readThroughRpc.data?.status === "invalid"
+                ? ` — ${readThroughRpc.data.error}`
+                : ""}
+            </Text>
+            <Button
+              label={isResetting ? "Resetting..." : "Reset host settings document"}
+              variant="ghost"
+              size="sm"
+              disabled={!handleAvailable || isResetting}
+              onPress={() => {
+                triggerHaptic("warning");
+                resetSettings({ revision });
+              }}
+            />
+          </Stack>
+
+          {error ? (
+            <Text style={{ color: colors.statusDanger, ...typography.caption }}>
+              Snapshot error: {error.message}
+            </Text>
+          ) : null}
+        </Card>
+
+        <Card variant="elevated">
+          <Card.Header
+            title="What this demo proves"
+            subtitle="Upstream 0.9 server settings handle vs our helper storage layer"
+          />
+          <Stack gap={4}>
+            <Text style={{ color: colors.foreground, ...typography.bodyStrong }}>
+              <StatusDot variant={handleAvailable ? "success" : "warning"} />{" "}
+              {handleAvailable
+                ? "registerSettings() returned a handle"
+                : "handle unavailable on this runtime"}
+            </Text>
+            <Text style={{ color: colors.foregroundMuted, ...typography.caption }}>
+              The daemon reads and subscribes through the handle returned by
+              registerSettings(); nothing here touches paseo-plugin-helper's
+              PluginStorage/registerSettingsRpc. The host owns persistence
+              (revision-checked, atomic) and the client writes through the same
+              document via the auto-registered settings RPC.
+            </Text>
+          </Stack>
+
+          <CodeBlock
+            language="typescript"
+            title="server/index.server.ts"
+            code={`const settings = server.registerSettings(defineSettings({
+  id: "server-demo", scope: "host", version: 1,
+  schema: z.object({ label: z.string().default("upstream handle demo"), ... }),
+}));
+
+// Server-side read + change subscription (upstream 0.9.0-beta.1+, PR #4674):
+settings.subscribe((state) => { /* { status, revision, values|error } */ });
+const state = await settings.read();
+`}
+            copyable
+          />
+        </Card>
+      </Stack>
+    </ModalBody>
+  );
+}
+
+/**
+ * Registers the temp demo surface + sidebar entry. Returns a disposer, or null
+ * when the host does not expose surface registration.
+ */
+export function registerServerSettingsDemoSurface(
+  client: SidebarSurfaceRegistrar,
+): (() => void) | null {
+  if (!("addSurface" in client) || !("addSidebarItem" in client)) return null;
+  return registerSidebarSurface(client, {
+    id: "helper-demo-server-settings",
+    title: "Server Settings (temp)",
+    icon: "Sliders",
+    Component: ServerSettingsDemoSurface,
+  });
+}

package/client/vendor/paseo-plugin-helper/utils/clipboard.ts

@@ -24,16 +24,23 @@ export interface ClipboardEnvironment {
  * `react-native-web` `Clipboard.setString` reports success even when its
  * `document.execCommand("copy")` fails, which leaves the previous clipboard
  * item in place while the UI claims success (xpufx-org/paseo#278); it is only
- * usable off-DOM (native), where it is the real platform clipboard. In a DOM
- * the checked `execCommand` fallback is preferred to that unverifiable path.
+ * usable off-DOM (native), where it is the real platform clipboard. The same
+ * applies to any `setStringAsync` whose DOM fallback is that unverified
+ * `execCommand`. In a DOM the checked `execCommand` fallback is preferred to
+ * those unverifiable paths.
  */
 export function clipboardTierOrder(env: ClipboardEnvironment): ClipboardTier[] {
   const tiers: ClipboardTier[] = [];
   if (env.hasNavigatorClipboard) tiers.push("navigator");
   if (env.hasHostCopyText) tiers.push("host");
-  if (env.hasRnSetStringAsync) {
+  // On a DOM both RN-web paths are unverifiable: `setString` reports success
+  // even when its `execCommand` no-ops, and a `setStringAsync` that falls back
+  // to it does the same. Off-DOM they are the real native clipboard, so they
+  // lead there; on a DOM only the checked `execCommand` fallback is honest.
+  const rnDomOk = !env.isDom;
+  if (env.hasRnSetStringAsync && rnDomOk) {
     tiers.push("rnAsync");
-  } else if (env.hasRnClipboard && !env.isDom) {
+  } else if (env.hasRnClipboard && rnDomOk) {
     tiers.push("rnSync");
   }
   tiers.push("execCommand");

package/index.client.tsx

@@ -0,0 +1,14 @@
+import type { PluginClientContext } from "@getpaseo/plugin/client";
+import { contributeClient } from "./client/pill.js";
+import { registerServerSettingsDemoSurface } from "./client/server-settings.js";
+
+export default function contribute(client: PluginClientContext) {
+  const cleanupPill = contributeClient(client);
+  // TEMP DEMO (issue #62): a sidebar page showing the upstream server
+  // settings handle. Not wired into the production pill/modal surfaces.
+  const cleanupSettingsSurface = registerServerSettingsDemoSurface(client);
+  return () => {
+    cleanupPill();
+    cleanupSettingsSurface?.();
+  };
+}

package/index.server.ts

@@ -0,0 +1,55 @@
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import {
+  demoSettingsContract,
+  getDemoDataRpc,
+  triggerDemoActionRpc,
+  demoAgentIdentityContract,
+  demoBeaconSetContract,
+  demoBeaconBlinkContract,
+  demoBeaconClearContract,
+} from "./shared/demo.js";
+import {
+  handleGetDemoData,
+  handleTriggerDemoAction,
+  handleGetAgentIdentity,
+  handleDemoBeaconSet,
+  handleDemoBeaconBlink,
+  handleDemoBeaconClear,
+  settingsHandlers,
+  backgroundWorker,
+  demoBeacon,
+  log,
+} from "./server/demo.js";
+import { suiteSettings, suiteSettingsHandlers } from "./server/suite-settings.js";
+import { demoSettingsSnapshotContract } from "./shared/server-settings.js";
+import {
+  handleGetServerSettingsSnapshot,
+  registerDemoServerSettings,
+} from "./server/server-settings.js";
+
+export default function contribute(server: PluginServerContext) {
+  // TEMP DEMO (issue #62): upstream registerSettings() -> read()/subscribe().
+  const serverSettings = registerDemoServerSettings(server);
+  server.handle(demoSettingsSnapshotContract, handleGetServerSettingsSnapshot);
+  server.handle(demoSettingsContract.get, settingsHandlers.get);
+  server.handle(demoSettingsContract.update, settingsHandlers.update);
+  server.handle(demoSettingsContract.reset, settingsHandlers.reset);
+  server.handle(suiteSettings.contract.get, suiteSettingsHandlers.get);
+  server.handle(suiteSettings.contract.update, suiteSettingsHandlers.update);
+  server.handle(suiteSettings.contract.reset, suiteSettingsHandlers.reset);
+  server.handle(getDemoDataRpc, handleGetDemoData);
+  server.handle(triggerDemoActionRpc, handleTriggerDemoAction);
+  server.handle(demoAgentIdentityContract, handleGetAgentIdentity);
+  server.handle(demoBeaconSetContract, handleDemoBeaconSet);
+  server.handle(demoBeaconBlinkContract, handleDemoBeaconBlink);
+  server.handle(demoBeaconClearContract, handleDemoBeaconClear);
+
+  log.info("Helper demo server handlers registered");
+
+  return () => {
+    backgroundWorker.stop();
+    demoBeacon.stopAll();
+    serverSettings.dispose();
+    log.info("Helper demo server background task stopped");
+  };
+}

package/package.json

@@ -2,10 +2,11 @@
   "name": "@xpufx/paseo-helper-demo",
   "private": false,
   "license": "MIT",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "scripts": {
     "stamp": "node -e \"import('./server/vendor/paseo-plugin-helper/version.ts').then(m => m.stampVersion({ targetFile: 'shared/version.ts' }))\"",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
   },
   "devDependencies": {
     "@getpaseo/plugin": "0.9.0-beta.2",
@@ -14,12 +15,15 @@
     "react": "19.1.0",
     "react-native": "0.81.5",
     "typescript": "^5.9.3",
+    "vitest": "^3.0.0",
     "zod": "^4.4.3"
   },
   "files": [
     "paseo-plugin.json",
     "README.md",
     "LICENSE",
+    "index.client.tsx",
+    "index.server.ts",
     "client",
     "server",
     "shared",

package/server/server-settings.ts

@@ -0,0 +1,177 @@
+import type {
+  PluginHandlerContext,
+  PluginServerContext,
+} from "@getpaseo/plugin/server";
+import type { SettingsDefinition } from "@getpaseo/plugin";
+import { createPluginLogger } from "paseo-plugin-helper/server";
+import {
+  buildServerSettingsSnapshot,
+  demoSettingsDefinition,
+  DEMO_SERVER_SETTINGS_EXPECTED_PATH,
+  DEMO_SERVER_SETTINGS_ID,
+  type ServerSettingsHandleState,
+  type ServerSettingsSnapshot,
+} from "../shared/server-settings.js";
+
+// Own logger so this module is importable without the demo's background task.
+const log = createPluginLogger("helper-demo", {
+  banner: false,
+  subsystem: "server-settings",
+});
+
+type HandleState = ServerSettingsHandleState;
+
+/**
+ * Structural shape of upstream's 0.9 `PluginSettings` handle. Typed locally so
+ * the module compiles and degrades cleanly on the 0.8 SDK, where
+ * `registerSettings()` returns `void` and no handle exists.
+ */
+interface SettingsHandleLike {
+  read(): Promise<HandleState>;
+  subscribe(listener: (state: HandleState) => void | Promise<void>): () => void;
+}
+
+interface RegisterSettingsCapable {
+  registerSettings(definition: SettingsDefinition<typeof demoSettingsDefinition.schema>): unknown;
+}
+
+function isSettingsHandle(value: unknown): value is SettingsHandleLike {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as { read?: unknown; subscribe?: unknown };
+  return typeof candidate.read === "function" && typeof candidate.subscribe === "function";
+}
+
+/**
+ * TEMP DEMO (issue #62): owns the upstream server settings handle for this
+ * plugin installation. Everything the demo shows about "server settings" comes
+ * from `handle.read()`/`handle.subscribe()` below - never from the helper's
+ * `PluginStorage`/`registerSettingsRpc` layer.
+ */
+class DemoSettingsHandle {
+  private readonly handle: SettingsHandleLike | null;
+  private readonly unavailableReason: string | null;
+  private current: HandleState | null = null;
+  private readCount = 0;
+  private eventCount = 0;
+  private lastEventAt: string | null = null;
+  private lastEventStatus: "ready" | "invalid" | null = null;
+  private subscribed = false;
+  private unsubscribe: (() => void) | null = null;
+
+  constructor(handle: SettingsHandleLike | null, unavailableReason: string | null) {
+    this.handle = handle;
+    this.unavailableReason = unavailableReason;
+  }
+
+  /**
+   * Subscribe before the first read so a concurrent client write during startup
+   * is not missed; the initial `read()` below establishes the baseline.
+   */
+  async initialize(): Promise<void> {
+    if (this.handle) {
+      this.unsubscribe = this.handle.subscribe((state) => {
+        this.eventCount += 1;
+        this.lastEventAt = new Date().toISOString();
+        this.lastEventStatus = state.status === "ready" ? "ready" : "invalid";
+        this.current = state;
+        log.info("Demo upstream settings handle observed a change", {
+          status: state.status,
+          revision: state.revision,
+        });
+      });
+      this.subscribed = true;
+    }
+    await this.refresh();
+  }
+
+  /** Reads through the upstream handle and returns the current snapshot. */
+  async refresh(): Promise<ServerSettingsSnapshot> {
+    if (!this.handle) return this.snapshot();
+    try {
+      this.current = await this.handle.read();
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      this.current = { status: "invalid", revision: "unknown", error: detail };
+    }
+    this.readCount += 1;
+    return this.snapshot();
+  }
+
+  dispose(): void {
+    this.unsubscribe?.();
+    this.unsubscribe = null;
+    this.subscribed = false;
+  }
+
+  private snapshot(): ServerSettingsSnapshot {
+    return buildServerSettingsSnapshot({
+      settingsId: DEMO_SERVER_SETTINGS_ID,
+      expectedPath: DEMO_SERVER_SETTINGS_EXPECTED_PATH,
+      handleAvailable: this.handle !== null,
+      unavailableReason: this.unavailableReason,
+      subscribed: this.subscribed,
+      readCount: this.readCount,
+      eventCount: this.eventCount,
+      lastEventAt: this.lastEventAt,
+      lastEventStatus: this.lastEventStatus,
+      schemaVersion: demoSettingsDefinition.version,
+      current: this.current,
+    });
+  }
+}
+
+let activeHandle: DemoSettingsHandle | null = null;
+
+/**
+ * Registers the host-scoped demo settings document via upstream
+ * `registerSettings()` and captures the returned handle. Called once from
+ * `contribute()`; the async `initialize()` is intentionally not awaited so the
+ * synchronous contribution contract is preserved.
+ */
+export function registerDemoServerSettings(server: PluginServerContext): DemoSettingsHandle {
+  const capable = server as unknown as RegisterSettingsCapable;
+  const returned = capable.registerSettings(demoSettingsDefinition);
+
+  let handle: SettingsHandleLike | null = null;
+  let reason: string | null = null;
+  if (isSettingsHandle(returned)) {
+    handle = returned;
+  } else {
+    reason =
+      "registerSettings() did not return a PluginSettings handle. On Paseo < 0.9.0-beta.1 it returns void (the handle shipped in 0.9.0-beta.1, upstream PR #4674); this build is running against an older host runtime.";
+  }
+
+  const demo = new DemoSettingsHandle(handle, reason);
+  activeHandle = demo;
+  void demo.initialize().catch((error) => {
+    log.error("Demo upstream settings handle failed to initialize", error);
+  });
+  return demo;
+}
+
+function unavailableSnapshot(): ServerSettingsSnapshot {
+  return buildServerSettingsSnapshot({
+    settingsId: DEMO_SERVER_SETTINGS_ID,
+    expectedPath: DEMO_SERVER_SETTINGS_EXPECTED_PATH,
+    handleAvailable: false,
+    unavailableReason: "Settings handle was not registered (plugin server did not initialize it).",
+    subscribed: false,
+    readCount: 0,
+    eventCount: 0,
+    lastEventAt: null,
+    lastEventStatus: null,
+    schemaVersion: demoSettingsDefinition.version,
+    current: null,
+  });
+}
+
+/** RPC handler backing the temp demo surface's snapshot read. */
+export async function handleGetServerSettingsSnapshot(
+  _input: Record<string, never>,
+  _context?: PluginHandlerContext,
+): Promise<ServerSettingsSnapshot> {
+  if (!activeHandle) return unavailableSnapshot();
+  return activeHandle.refresh();
+}
+
+export type { DemoSettingsHandle };

package/shared/server-settings.ts

@@ -0,0 +1,143 @@
+import { defineSettings, settingsRpc } from "@getpaseo/plugin";
+import { z } from "zod";
+import { defineContract } from "paseo-plugin-helper/shared";
+
+/**
+ * TEMP DEMO (issue #62): upstream server-side settings handle.
+ *
+ * The `SettingsDefinition` below is the single source of truth for a
+ * host-scoped settings document. Upstream `registerSettings()` on the server
+ * now returns a `PluginSettings` handle with `read()`/`subscribe()`; the client
+ * half is the auto-registered `settings.<id>.*` RPC plus the host `useSettings()`
+ * hook built on it. This module is intentionally outside our helper's
+ * `PluginStorage`/`registerSettingsRpc` layer - that is the point of the demo.
+ */
+export const DEMO_SERVER_SETTINGS_ID = "server-demo";
+
+/** Upstream store layout, shown in the demo UI: `~/.paseo/plugin-settings/<pluginId>/<id>.json`. */
+export const DEMO_SERVER_SETTINGS_EXPECTED_PATH =
+  "~/.paseo/plugin-settings/paseo-helper-demo/server-demo.json";
+
+export const DemoSettingsSchema = z.object({
+  label: z.string().min(1).default("upstream handle demo"),
+  enabled: z.boolean().default(true),
+  threshold: z.number().int().min(0).max(100).default(70),
+});
+
+export type DemoSettingsValues = z.infer<typeof DemoSettingsSchema>;
+
+export const demoSettingsDefinition = defineSettings({
+  id: DEMO_SERVER_SETTINGS_ID,
+  scope: "host",
+  version: 1,
+  schema: DemoSettingsSchema,
+});
+
+/** The host RPC the server handle auto-registers; the client writes through it. */
+export const demoSettingsRpc = settingsRpc(DEMO_SERVER_SETTINGS_ID);
+
+/**
+ * Server-handle snapshot: what the daemon process has observed via the
+ * upstream handle's `read()` and `subscribe()`, not our helper storage.
+ */
+export const ServerSettingsSnapshotSchema = z.object({
+  settingsId: z.string(),
+  expectedPath: z.string(),
+  handleAvailable: z.boolean(),
+  unavailableReason: z.string().nullable(),
+  subscribed: z.boolean(),
+  status: z.enum(["uninitialized", "ready", "invalid"]),
+  revision: z.string(),
+  values: DemoSettingsSchema.nullable(),
+  error: z.string().nullable(),
+  readCount: z.number(),
+  eventCount: z.number(),
+  lastEventAt: z.string().nullable(),
+  lastEventStatus: z.enum(["ready", "invalid"]).nullable(),
+  schemaVersion: z.number(),
+});
+
+export type ServerSettingsSnapshot = z.infer<typeof ServerSettingsSnapshotSchema>;
+
+/** A single state emitted by the upstream handle (structurally mirrors 0.9's PluginSettingsState). */
+export type ServerSettingsHandleState =
+  | { status: "ready"; revision: string; values: unknown }
+  | { status: "invalid"; revision: string; error: string };
+
+export interface ServerSettingsObservation {
+  settingsId: string;
+  expectedPath: string;
+  handleAvailable: boolean;
+  unavailableReason: string | null;
+  subscribed: boolean;
+  readCount: number;
+  eventCount: number;
+  lastEventAt: string | null;
+  lastEventStatus: "ready" | "invalid" | null;
+  schemaVersion: number;
+  current: ServerSettingsHandleState | null;
+}
+
+/**
+ * Pure projection of the daemon's handle observations into the RPC snapshot
+ * shape. Kept free of the SDK so it is unit-testable; the server class only
+ * tracks counters and calls this.
+ */
+export function buildServerSettingsSnapshot(
+  observation: ServerSettingsObservation,
+): ServerSettingsSnapshot {
+  const base = {
+    settingsId: observation.settingsId,
+    expectedPath: observation.expectedPath,
+    handleAvailable: observation.handleAvailable,
+    unavailableReason: observation.unavailableReason,
+    subscribed: observation.subscribed,
+    readCount: observation.readCount,
+    eventCount: observation.eventCount,
+    lastEventAt: observation.lastEventAt,
+    lastEventStatus: observation.lastEventStatus,
+    schemaVersion: observation.schemaVersion,
+  };
+  if (!observation.current) {
+    return ServerSettingsSnapshotSchema.parse({
+      ...base,
+      status: "uninitialized",
+      revision: "missing",
+      values: null,
+      error: null,
+    });
+  }
+  if (observation.current.status === "ready") {
+    const parsed = DemoSettingsSchema.safeParse(observation.current.values);
+    if (!parsed.success) {
+      return ServerSettingsSnapshotSchema.parse({
+        ...base,
+        status: "invalid",
+        revision: observation.current.revision,
+        values: null,
+        error: parsed.error.message,
+      });
+    }
+    return ServerSettingsSnapshotSchema.parse({
+      ...base,
+      status: "ready",
+      revision: observation.current.revision,
+      values: parsed.data,
+      error: null,
+    });
+  }
+  return ServerSettingsSnapshotSchema.parse({
+    ...base,
+    status: "invalid",
+    revision: observation.current.revision,
+    values: null,
+    error: observation.current.error,
+  });
+}
+
+export const demoSettingsSnapshotContract = defineContract({
+  name: "helper-demo.server-settings.snapshot",
+  description: "Server handle state observed via upstream registerSettings().read()/subscribe()",
+  input: z.object({}),
+  output: ServerSettingsSnapshotSchema,
+});