deepspace 0.3.11 → 0.4.1

package/dist/index.d.ts

@@ -396,6 +396,7 @@ declare const MSG: {
     readonly USER_LIST: "user.list";
     readonly SET_ROLE: "user.set_role";
     readonly USER_UPDATE: "user.update";
+    readonly AUTH: "auth";
     readonly YJS_JOIN: "yjs.join";
     readonly YJS_LEAVE: "yjs.leave";
     readonly ACK: "records.ack";
@@ -639,6 +640,8 @@ type ServerMessage = BaseMessage<typeof MSG.QUERY_RESULT, {
     error: string;
 }> | BaseMessage<typeof MSG.RESUBSCRIBE, EmptyPayload> | BaseMessage<typeof MSG.LIST_SCHEMAS, {
     schemas: unknown;
+}> | BaseMessage<typeof MSG.AUTH, {
+    canWrite: boolean;
 }> | BaseMessage<typeof MSG.USER_INFO, unknown> | BaseMessage<typeof MSG.USER_LIST, {
     users: unknown[];
 }> | BaseMessage<typeof MSG.YJS_JOIN, {
@@ -5972,13 +5975,20 @@ interface UseGameRoomResult {
     running: boolean;
     /** Whether WebSocket is connected */
     connected: boolean;
-    /** Send a game input */
+    /**
+     * Whether this connection has write access. False for viewers /
+     * unauthenticated spectators — they receive state broadcasts but the
+     * send callbacks below no-op. UIs should disable input controls when
+     * false so spectators see why their actions don't take effect.
+     */
+    canWrite: boolean;
+    /** Send a game input (no-op for spectators) */
     sendInput: (action: string, data?: Record<string, unknown>) => void;
-    /** Mark self as ready */
+    /** Mark self as ready (no-op for spectators) */
     setReady: () => void;
-    /** Request game start */
+    /** Request game start (no-op for spectators) */
     startGame: () => void;
-    /** Request game end */
+    /** Request game end (no-op for spectators) */
     endGame: () => void;
 }
 declare function useGameRoom(roomId: string): UseGameRoomResult;
@@ -6019,21 +6029,28 @@ interface UseCanvasResult {
     viewports: ViewportClient[];
     /** Whether WebSocket is connected */
     connected: boolean;
-    /** Add a shape */
+    /**
+     * Whether this connection has write access (member/admin role). The
+     * write callbacks below no-op when this is false; UIs should also use
+     * it to disable controls so viewers see why their clicks do nothing.
+     * Viewport reporting stays available regardless — it's presence info.
+     */
+    canWrite: boolean;
+    /** Add a shape (no-op when canWrite is false) */
     addShape: (shape: Partial<CanvasShapeClient>) => void;
-    /** Move a shape */
+    /** Move a shape (no-op when canWrite is false) */
     moveShape: (shapeId: string, x: number, y: number) => void;
-    /** Resize a shape */
+    /** Resize a shape (no-op when canWrite is false) */
     resizeShape: (shapeId: string, width: number, height: number, x?: number, y?: number) => void;
-    /** Delete a shape */
+    /** Delete a shape (no-op when canWrite is false) */
     deleteShape: (shapeId: string) => void;
-    /** Update shape properties */
+    /** Update shape properties (no-op when canWrite is false) */
     updateShape: (shapeId: string, props: Record<string, unknown>) => void;
-    /** Report local viewport */
+    /** Report local viewport (allowed for viewers — presence-like) */
     setViewport: (viewport: Omit<ViewportClient, 'userId'>) => void;
-    /** Undo last action */
+    /** Undo last action (no-op when canWrite is false) */
     undo: () => void;
-    /** Redo last undone action */
+    /** Redo last undone action (no-op when canWrite is false) */
     redo: () => void;
 }
 declare function useCanvas(roomId: string): UseCanvasResult;
@@ -6070,11 +6087,18 @@ interface UseCronMonitorResult {
     history: CronHistoryEntry[];
     /** Whether WebSocket is connected */
     connected: boolean;
-    /** Manually trigger a task */
+    /**
+     * Whether this connection can mutate cron state (trigger / pause /
+     * resume). False for viewers and unauthenticated connections — the
+     * mutation callbacks below no-op and UIs should disable those
+     * controls. Reading tasks/history stays available either way.
+     */
+    canWrite: boolean;
+    /** Manually trigger a task (no-op when canWrite is false) */
     trigger: (taskName: string) => void;
-    /** Pause a task */
+    /** Pause a task (no-op when canWrite is false) */
     pause: (taskName: string) => void;
-    /** Resume a paused task */
+    /** Resume a paused task (no-op when canWrite is false) */
     resume: (taskName: string) => void;
 }
 declare function useCronMonitor(roomId: string): UseCronMonitorResult;
@@ -6206,17 +6230,23 @@ declare function toConnectionStatus(queryStatus: string): ConnectionStatus;
 /**
  * useR2Files — Scoped file storage hook for DeepSpace apps.
  *
- * Provides upload, download, list, and delete for files in R2, scoped to
- * the current app ("self" — uses hostname-based scoping on the server).
+ * Provides upload, download, list, and delete for files in R2.
+ *
+ * Two scopes are supported via the `scope` option:
+ *   - `'self'` (default): per-user storage. Reads require auth.
+ *   - `'app'`: app-wide storage. Reads are public — the upload URL works
+ *     directly as an `<img src>`. Use for avatars, logos, etc.
  *
  * @example
  * ```tsx
- * const { upload, downloadFile, deleteFile, list } = useR2Files()
+ * // Per-user files (default):
+ * const { upload, downloadFile } = useR2Files()
  * await upload(myFile, 'photo.png')
  *
- * const files = await list()
- * await downloadFile(files[0])  // uses originalName automatically
- * await deleteFile(files[0])
+ * // App-shared files (public reads — usable in <img src>):
+ * const { upload } = useR2Files({ scope: 'app' })
+ * const r = await upload(file, `avatars/${userId}.png`)
+ * // r.url is a plain, anon-readable URL.
  * ```
  */
 interface R2UploadResult {
@@ -6290,17 +6320,29 @@ interface UseR2FilesReturn {
     /**
      * Build a plain URL for a file. Accepts an R2FileInfo or a raw key string.
      *
-     * **Note**: This URL has no auth token attached. It only works for
-     * unauthenticated reads on deployed sites where the prefix is derived
-     * from the hostname. For authenticated access, use `downloadFile` or
-     * `readFile` instead.
+     * **Note**: This URL has no auth token attached. It works for `'app'`-scope
+     * files (which are publicly readable) but not for `'self'`-scope files —
+     * those require an Authorization header, so use `readFile` / `downloadFile`.
      */
     getUrl: (fileOrKey: R2FileInfo | string) => string;
     /** Whether an upload is currently in progress. */
     isUploading: boolean;
 }
+/**
+ * Scope controls where files live and who can read them:
+ *
+ *  - `'self'` (default) — `apps/<app>/users/<userId>/…`. Per-user storage.
+ *    Reads require the caller's auth token; not usable from a plain `<img>`
+ *    or unauthenticated browser request.
+ *  - `'app'` — `apps/<app>/…`. Shared by everyone in the app. Reads are
+ *    public (no auth header needed), so the upload URL works directly as
+ *    an `<img src>`. Use this for avatars, logos, attachments, and other
+ *    assets meant to be embedded in pages.
+ *
+ * Uploads under `'app'` still require a signed-in user.
+ */
 type R2Scope = {
-    scope?: 'self';
+    scope?: 'self' | 'app';
 };
 declare function useR2Files(options?: R2Scope): UseR2FilesReturn;
 

package/dist/index.js

@@ -407,6 +407,13 @@ var MSG = {
   USER_LIST: "user.list",
   SET_ROLE: "user.set_role",
   USER_UPDATE: "user.update",
+  // ---- Auth signal -----------------------------------------------------
+  // Server → client one-shot on connect from rooms that enforce role-based
+  // writes (Canvas, Game, Cron). Tells the client whether this connection
+  // can write so its hook can disable local write APIs and the UI can
+  // render controls accordingly. Without this, a viewer's click would
+  // round-trip to the server and silently come back as ERROR.
+  AUTH: "auth",
   // ---- Yjs JSON control frames (binary sync lives in ./yjs.ts) ---------
   YJS_JOIN: "yjs.join",
   YJS_LEAVE: "yjs.leave",
@@ -717,12 +724,17 @@ function DeepSpaceAuthProvider({ children }) {
 }
 
 // src/client/auth/hooks.ts
+var sessionHasResolved = false;
+function stickyIsLoaded(isPending) {
+  if (!isPending) sessionHasResolved = true;
+  return sessionHasResolved;
+}
 function useAuth() {
   const session = useSession();
   const isSignedIn = !!session.data?.user;
   const userId = session.data?.user?.id ?? null;
   return {
-    isLoaded: !session.isPending,
+    isLoaded: stickyIsLoaded(session.isPending),
     isSignedIn,
     userId,
     sessionId: session.data?.session?.id ?? null
@@ -732,7 +744,7 @@ function useAuthUser() {
   const session = useSession();
   const user = session.data?.user ?? null;
   return {
-    isLoaded: !session.isPending,
+    isLoaded: stickyIsLoaded(session.isPending),
     isSignedIn: !!user,
     user: user ? {
       id: user.id,
@@ -880,7 +892,35 @@ function AuthOverlay({
                   }
                 )
               ] }),
-              /* @__PURE__ */ jsxs2("div", { className: "mt-5 flex items-center justify-center gap-1.5 text-[11px] text-muted-foreground", children: [
+              /* @__PURE__ */ jsxs2("p", { className: "mt-5 text-xs leading-snug text-muted-foreground", children: [
+                "By continuing, you agree to the DeepSpace",
+                " ",
+                /* @__PURE__ */ jsx2(
+                  "a",
+                  {
+                    href: "https://deep.space/terms",
+                    target: "_blank",
+                    rel: "noopener noreferrer",
+                    className: "underline hover:text-foreground",
+                    children: "Terms of Service"
+                  }
+                ),
+                " ",
+                "and",
+                " ",
+                /* @__PURE__ */ jsx2(
+                  "a",
+                  {
+                    href: "https://deep.space/privacy",
+                    target: "_blank",
+                    rel: "noopener noreferrer",
+                    className: "underline hover:text-foreground",
+                    children: "Privacy Policy"
+                  }
+                ),
+                "."
+              ] }),
+              /* @__PURE__ */ jsxs2("div", { className: "mt-4 flex items-center justify-center gap-1.5 text-[11px] text-muted-foreground", children: [
                 /* @__PURE__ */ jsx2("svg", { width: "12", height: "12", viewBox: "0 0 24 24", fill: "currentColor", opacity: "0.5", "aria-hidden": true, children: /* @__PURE__ */ jsx2("circle", { cx: "12", cy: "12", r: "10" }) }),
                 "Powered by DeepSpace"
               ] })
@@ -2848,6 +2888,7 @@ function useGameRoom(roomId) {
   const [players, setPlayers] = useState8([]);
   const [running, setRunning] = useState8(false);
   const [connected, setConnected] = useState8(false);
+  const [canWrite, setCanWrite] = useState8(false);
   const wsRef = useRef9(null);
   useEffect11(() => {
     let ws = null;
@@ -2869,6 +2910,9 @@ function useGameRoom(roomId) {
       };
       ws.onmessage = (event) => {
         dispatch(event.data, {
+          [MSG.AUTH]: (p) => {
+            setCanWrite(p.canWrite);
+          },
           [MSG.GAME_STATE]: (p) => {
             setGameState(p.state);
             setTick(p.tick);
@@ -2906,6 +2950,7 @@ function useGameRoom(roomId) {
         wsLog("disconnected", `game:${roomId}`);
         wsRef.current = null;
         setConnected(false);
+        setCanWrite(false);
         if (alive) reconnectTimer = setTimeout(connect, 1e3);
       };
       ws.onerror = () => ws?.close();
@@ -2924,27 +2969,23 @@ function useGameRoom(roomId) {
       wsRef.current = null;
     };
   }, [roomId]);
-  const sendInput = useCallback10((action, data = {}) => {
-    const ws = wsRef.current;
-    if (!ws || ws.readyState !== WebSocket.OPEN) return;
-    ws.send(encode(clientBuild.gameInput(action, data)));
-  }, []);
-  const setReady = useCallback10(() => {
-    const ws = wsRef.current;
-    if (!ws || ws.readyState !== WebSocket.OPEN) return;
-    ws.send(encode(clientBuild.gamePlayerReady()));
-  }, []);
-  const startGame = useCallback10(() => {
-    const ws = wsRef.current;
-    if (!ws || ws.readyState !== WebSocket.OPEN) return;
-    ws.send(encode(clientBuild.gameStart()));
-  }, []);
-  const endGame = useCallback10(() => {
-    const ws = wsRef.current;
-    if (!ws || ws.readyState !== WebSocket.OPEN) return;
-    ws.send(encode(clientBuild.gameEnd()));
-  }, []);
-  return { state: gameState, tick, players, running, connected, sendInput, setReady, startGame, endGame };
+  const send = useCallback10(
+    (message) => {
+      if (!canWrite) return;
+      const ws = wsRef.current;
+      if (!ws || ws.readyState !== WebSocket.OPEN) return;
+      ws.send(encode(message));
+    },
+    [canWrite]
+  );
+  const sendInput = useCallback10(
+    (action, data = {}) => send(clientBuild.gameInput(action, data)),
+    [send]
+  );
+  const setReady = useCallback10(() => send(clientBuild.gamePlayerReady()), [send]);
+  const startGame = useCallback10(() => send(clientBuild.gameStart()), [send]);
+  const endGame = useCallback10(() => send(clientBuild.gameEnd()), [send]);
+  return { state: gameState, tick, players, running, connected, canWrite, sendInput, setReady, startGame, endGame };
 }
 
 // src/client/storage/hooks/useCanvas.ts
@@ -2953,6 +2994,7 @@ function useCanvas(roomId) {
   const [shapes, setShapes] = useState9([]);
   const [viewports, setViewports] = useState9([]);
   const [connected, setConnected] = useState9(false);
+  const [canWrite, setCanWrite] = useState9(false);
   const wsRef = useRef10(null);
   useEffect12(() => {
     let ws = null;
@@ -2974,6 +3016,9 @@ function useCanvas(roomId) {
       };
       ws.onmessage = (event) => {
         dispatch(event.data, {
+          [MSG.AUTH]: (p) => {
+            setCanWrite(p.canWrite);
+          },
           [MSG.CANVAS_SHAPES]: (p) => {
             setShapes(p.shapes);
             setViewports(p.viewports);
@@ -3026,6 +3071,7 @@ function useCanvas(roomId) {
         wsLog("disconnected", `canvas:${roomId}`);
         wsRef.current = null;
         setConnected(false);
+        setCanWrite(false);
         if (alive) reconnectTimer = setTimeout(connect, 1e3);
       };
       ws.onerror = () => ws?.close();
@@ -3052,33 +3098,40 @@ function useCanvas(roomId) {
     },
     []
   );
+  const sendWrite = useCallback11(
+    (message) => {
+      if (!canWrite) return;
+      sendBuilt(message);
+    },
+    [sendBuilt, canWrite]
+  );
   const addShape = useCallback11(
-    (shape) => sendBuilt(clientBuild.canvasAdd(shape)),
-    [sendBuilt]
+    (shape) => sendWrite(clientBuild.canvasAdd(shape)),
+    [sendWrite]
   );
   const moveShape = useCallback11(
-    (shapeId, x, y) => sendBuilt(clientBuild.canvasMove(shapeId, x, y)),
-    [sendBuilt]
+    (shapeId, x, y) => sendWrite(clientBuild.canvasMove(shapeId, x, y)),
+    [sendWrite]
   );
   const resizeShape = useCallback11(
-    (shapeId, width, height, x, y) => sendBuilt(clientBuild.canvasResize(shapeId, width, height, x, y)),
-    [sendBuilt]
+    (shapeId, width, height, x, y) => sendWrite(clientBuild.canvasResize(shapeId, width, height, x, y)),
+    [sendWrite]
   );
   const deleteShape = useCallback11(
-    (shapeId) => sendBuilt(clientBuild.canvasDelete(shapeId)),
-    [sendBuilt]
+    (shapeId) => sendWrite(clientBuild.canvasDelete(shapeId)),
+    [sendWrite]
   );
   const updateShape = useCallback11(
-    (shapeId, props) => sendBuilt(clientBuild.canvasUpdate(shapeId, props)),
-    [sendBuilt]
+    (shapeId, props) => sendWrite(clientBuild.canvasUpdate(shapeId, props)),
+    [sendWrite]
   );
   const setViewport = useCallback11(
     (viewport) => sendBuilt(clientBuild.canvasViewport(viewport)),
     [sendBuilt]
   );
-  const undo = useCallback11(() => sendBuilt(clientBuild.canvasUndo()), [sendBuilt]);
-  const redo = useCallback11(() => sendBuilt(clientBuild.canvasRedo()), [sendBuilt]);
-  return { shapes, viewports, connected, addShape, moveShape, resizeShape, deleteShape, updateShape, setViewport, undo, redo };
+  const undo = useCallback11(() => sendWrite(clientBuild.canvasUndo()), [sendWrite]);
+  const redo = useCallback11(() => sendWrite(clientBuild.canvasRedo()), [sendWrite]);
+  return { shapes, viewports, connected, canWrite, addShape, moveShape, resizeShape, deleteShape, updateShape, setViewport, undo, redo };
 }
 
 // src/client/storage/hooks/useCronMonitor.ts
@@ -3087,6 +3140,7 @@ function useCronMonitor(roomId) {
   const [tasks, setTasks] = useState10([]);
   const [history, setHistory] = useState10([]);
   const [connected, setConnected] = useState10(false);
+  const [canWrite, setCanWrite] = useState10(false);
   const wsRef = useRef11(null);
   useEffect13(() => {
     let ws = null;
@@ -3104,6 +3158,9 @@ function useCronMonitor(roomId) {
       ws.onopen = () => setConnected(true);
       ws.onmessage = (event) => {
         dispatch(event.data, {
+          [MSG.AUTH]: (p) => {
+            setCanWrite(p.canWrite);
+          },
           [MSG.CRON_TASKS]: (p) => {
             setTasks(p.tasks);
           },
@@ -3119,6 +3176,7 @@ function useCronMonitor(roomId) {
       ws.onclose = () => {
         wsRef.current = null;
         setConnected(false);
+        setCanWrite(false);
         if (alive) reconnectTimer = setTimeout(connect, 1e3);
       };
       ws.onerror = () => ws?.close();
@@ -3131,27 +3189,28 @@ function useCronMonitor(roomId) {
       wsRef.current = null;
     };
   }, [roomId]);
-  const sendBuilt = useCallback12(
+  const sendWrite = useCallback12(
     (message) => {
+      if (!canWrite) return;
       const ws = wsRef.current;
       if (!ws || ws.readyState !== WebSocket.OPEN) return;
       ws.send(encode(message));
     },
-    []
+    [canWrite]
   );
   const trigger = useCallback12(
-    (taskName) => sendBuilt(clientBuild.cronTrigger(taskName)),
-    [sendBuilt]
+    (taskName) => sendWrite(clientBuild.cronTrigger(taskName)),
+    [sendWrite]
   );
   const pause = useCallback12(
-    (taskName) => sendBuilt(clientBuild.cronPause(taskName)),
-    [sendBuilt]
+    (taskName) => sendWrite(clientBuild.cronPause(taskName)),
+    [sendWrite]
   );
   const resume = useCallback12(
-    (taskName) => sendBuilt(clientBuild.cronResume(taskName)),
-    [sendBuilt]
+    (taskName) => sendWrite(clientBuild.cronResume(taskName)),
+    [sendWrite]
   );
-  return { tasks, history, connected, trigger, pause, resume };
+  return { tasks, history, connected, canWrite, trigger, pause, resume };
 }
 
 // src/client/storage/hooks/useJobs.ts
@@ -3376,11 +3435,12 @@ function resolveFile(fileOrKey) {
 }
 function useR2Files(options) {
   const [isUploading, setIsUploading] = useState13(false);
+  const scope = options?.scope ?? "self";
   const scopeParams = useMemo10(() => {
     const params = new URLSearchParams();
-    params.set("scope", "self");
+    params.set("scope", scope);
     return params.toString();
-  }, []);
+  }, [scope]);
   const authHeaders = useCallback15(async () => {
     const token = await getAuthToken();
     if (token) {