comment-mode 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Commentator
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,145 @@
+## Comment Mode
+
+Embeddable commenting for live prototypes (Next.js / React) that talks to your Comment Mode API.
+
+### Pushing to GitHub
+
+The project is already a git repo with an initial commit. To put it on GitHub:
+
+1. **Create a new repository** on [GitHub](https://github.com/new): name it e.g. `commentator` (or `comment-mode`). Do **not** initialize with a README, .gitignore, or license—they already exist locally.
+2. **Add the remote and push:**
+   ```bash
+   git remote add origin https://github.com/YOUR_USERNAME/commentator.git
+   git branch -M main
+   git push -u origin main
+   ```
+   Replace `YOUR_USERNAME` with your GitHub username (or org) and `commentator` with the repo name you chose.
+
+### Installation
+
+```bash
+npm install comment-mode
+```
+
+### Basic usage
+
+```tsx
+import { CommentProvider, CommentOverlay } from "comment-mode";
+
+function App() {
+  return (
+    <CommentProvider
+      config={{
+        projectSlug: "my-prototype",
+        surfaceId: window.location.pathname,
+        // Optional: override if you self-host the API
+        // apiBaseUrl: "https://api.commentmode.dev",
+      }}
+    >
+      {/* your prototype UI */}
+      <CommentOverlay />
+    </CommentProvider>
+  );
+}
+```
+
+The current implementation includes:
+
+- **CommentProvider**: React context that holds configuration and talks to the Comment Mode HTTP API.
+- **CommentOverlay**: A fullscreen overlay with a toggle button, persisted pins (threads), and a basic comments panel per pin.
+- **useComments**: Hook exposing thread and comment APIs (create thread, load comments, add comment).
+
+By default, the package calls the shared API at `https://api.commentmode.dev`. You can override with `apiBaseUrl` in the config if you run your own backend.
+
+### Backend API sketch
+
+At minimum, the backend behind `apiBaseUrl` should expose:
+
+- **POST `/threads`**
+  - Request JSON:
+
+    ```json
+    {
+      "projectSlug": "my-prototype",
+      "surfaceId": "/some/route",
+      "anchorX": 0.42,
+      "anchorY": 0.17
+    }
+    ```
+
+  - Response JSON:
+
+    ```json
+    {
+      "id": "thread-uuid"
+    }
+    ```
+
+This backend can be implemented in a separate Next.js app that owns your Supabase credentials and inserts rows into `threads` (and later `comments`, `users`, etc.).
+
+### Running the shared API (one backend for everyone)
+
+If you want to run a **shared API** so that everyone who installs `comment-mode` can use it without running their own backend:
+
+1. **Deploy the API**  
+   The `commentator-api` folder in this repo is a Next.js app. Deploy it to [Vercel](https://vercel.com) (or similar):
+   - Connect your GitHub repo and set the **root directory** to `commentator-api` (or deploy from inside that folder).
+   - Add **Environment Variables** in the Vercel project:
+     - `SUPABASE_URL` — your Supabase project URL
+     - `SUPABASE_SERVICE_ROLE_KEY` — service role key (API uses this for threads/comments)
+     - `SUPABASE_ANON_KEY` — anon key (exposed to the client via `/auth/config` for Supabase Auth)
+   - Deploy. Add your custom domain (e.g. `api.commentmode.dev`) in Vercel so the API is served there.
+
+2. **SDK default**  
+   The package already defaults to `https://api.commentmode.dev` (see `src/constants.ts`). After you deploy the API to that URL, run `npm run build` and publish the package; anyone who installs `comment-mode` will use your shared API by default.
+
+3. **Configure Supabase for production**  
+   In **Supabase Dashboard → Authentication → URL Configuration**:
+   - **Site URL**: your main production app URL (e.g. `https://commentmode.dev` or the URL of a prototype that uses the SDK).
+   - **Redirect URLs**: add every origin where the commenting UI will run (e.g. `https://commentmode.dev`, `https://commentmode.dev/**`, and any other prototype domains). You can add more later as people use the SDK on different sites.
+
+### Supabase URLs when going live
+
+If you run your own API (e.g. the `commentator-api` in this repo) and use Supabase Auth (magic link, GitHub, etc.), you must configure URLs in the **Supabase Dashboard** so auth works on production:
+
+1. **Authentication → URL Configuration**
+   - **Site URL**: set to your production app origin (e.g. `https://my-prototype.vercel.app`). This is the main URL where the SDK runs.
+   - **Redirect URLs**: add every origin where the commenting UI will load. For example:
+     - `https://my-prototype.vercel.app`
+     - `https://my-prototype.vercel.app/**`
+     - Any other prototype or app domains that use the same Comment Mode API.
+
+Without these, Supabase will block redirects from localhost-only and auth (sign-in, magic link) will fail on deployed sites.
+
+To build the package:
+
+```bash
+npm install
+npm run build
+```
+
+You can now link or publish the resulting package and import it into your Next.js prototypes.
+
+### Publishing to npm
+
+To publish this package as **comment-mode**:
+
+1. **npm account**  
+   Create an account at [npmjs.com](https://www.npmjs.com/signup) and log in with `npm login`.
+
+2. **Point repo URLs to your repo**  
+   In `package.json`, set `repository.url`, `bugs.url`, and `homepage` to your real GitHub (or other) repo (replace `your-org` with your org/username, e.g. `https://github.com/your-org/comment-mode`).
+
+3. **Optional: LICENSE**  
+   A root `LICENSE` file (e.g. MIT) is included; update the copyright holder if needed.
+
+4. **Publish**  
+   From the repo root:
+   ```bash
+   npm run build
+   npm publish
+   ```
+
+5. **Later releases**  
+   Bump `version` in `package.json` (e.g. `0.1.1`), then `npm publish` again.
+

package/dist/index.d.mts

@@ -0,0 +1,84 @@
+import React from 'react';
+import { SupabaseClient, User } from '@supabase/supabase-js';
+
+type CommentConfig = {
+    projectSlug: string;
+    surfaceId: string;
+    /**
+     * Optional override for the Comment Mode API base URL.
+     * Defaults to the shared API (see DEFAULT_API_BASE_URL in constants.ts).
+     */
+    apiBaseUrl?: string;
+};
+
+type CommentProviderProps = {
+    config: CommentConfig;
+    children: React.ReactNode;
+};
+declare function CommentProvider(props: CommentProviderProps): JSX.Element;
+
+type CommentSurfaceProps = {
+    children?: React.ReactNode;
+    style?: React.CSSProperties;
+    className?: string;
+};
+/**
+ * Wraps the area that can receive comment pins. When comment mode is on,
+ * mouse move highlights the element under the cursor and click creates a thread.
+ * Pins are rendered inside the surface so they scroll with the content.
+ * Must be used inside CommentProvider and wrap the same DOM that CommentOverlay covers.
+ */
+declare function CommentSurface(props: CommentSurfaceProps): JSX.Element;
+
+type CommentOverlayProps = {
+    position?: "left" | "right";
+};
+declare function CommentOverlay(props: CommentOverlayProps): JSX.Element;
+
+declare function CommentSettings(): JSX.Element;
+
+type ThreadAnchor = {
+    x: number;
+    y: number;
+};
+type Thread = {
+    id: string;
+    anchor: ThreadAnchor;
+    status: "open" | "resolved";
+};
+type Comment = {
+    id: string;
+    threadId: string;
+    body: string;
+    createdAt?: string;
+    authorName?: string | null;
+};
+
+declare function useComments(): {
+    config: CommentConfig;
+    threads: Thread[];
+    commentsByThread: Record<string, Comment[]>;
+    isLoading: boolean;
+    error: Error | null;
+    createThread: (anchor: ThreadAnchor, initialCommentBody?: string, initialAuthorName?: string | null) => Promise<Thread>;
+    loadComments: (threadId: string) => Promise<void>;
+    addComment: (threadId: string, body: string, authorName?: string | null) => Promise<Comment>;
+    deleteThread: (threadId: string) => Promise<void>;
+};
+
+type AuthUser = Pick<User, "id" | "email">;
+type AuthContextValue = {
+    supabase: SupabaseClient | null;
+    user: AuthUser | null;
+    accessToken: string | null;
+    isReady: boolean;
+    /** Resolved from GitHub: full_name, or username if name not set. Read-only. */
+    displayName: string;
+    signInWithEmail: (email: string) => Promise<void>;
+    signInWithGitHub: () => Promise<void>;
+    signOut: () => Promise<void>;
+};
+
+declare function useCommentAuth(): AuthContextValue;
+
+export { type CommentConfig, CommentOverlay, type CommentOverlayProps, CommentProvider, type CommentProviderProps, CommentSettings, CommentSurface, type CommentSurfaceProps, useCommentAuth, useComments };

package/dist/index.d.ts

@@ -0,0 +1,84 @@
+import React from 'react';
+import { SupabaseClient, User } from '@supabase/supabase-js';
+
+type CommentConfig = {
+    projectSlug: string;
+    surfaceId: string;
+    /**
+     * Optional override for the Comment Mode API base URL.
+     * Defaults to the shared API (see DEFAULT_API_BASE_URL in constants.ts).
+     */
+    apiBaseUrl?: string;
+};
+
+type CommentProviderProps = {
+    config: CommentConfig;
+    children: React.ReactNode;
+};
+declare function CommentProvider(props: CommentProviderProps): JSX.Element;
+
+type CommentSurfaceProps = {
+    children?: React.ReactNode;
+    style?: React.CSSProperties;
+    className?: string;
+};
+/**
+ * Wraps the area that can receive comment pins. When comment mode is on,
+ * mouse move highlights the element under the cursor and click creates a thread.
+ * Pins are rendered inside the surface so they scroll with the content.
+ * Must be used inside CommentProvider and wrap the same DOM that CommentOverlay covers.
+ */
+declare function CommentSurface(props: CommentSurfaceProps): JSX.Element;
+
+type CommentOverlayProps = {
+    position?: "left" | "right";
+};
+declare function CommentOverlay(props: CommentOverlayProps): JSX.Element;
+
+declare function CommentSettings(): JSX.Element;
+
+type ThreadAnchor = {
+    x: number;
+    y: number;
+};
+type Thread = {
+    id: string;
+    anchor: ThreadAnchor;
+    status: "open" | "resolved";
+};
+type Comment = {
+    id: string;
+    threadId: string;
+    body: string;
+    createdAt?: string;
+    authorName?: string | null;
+};
+
+declare function useComments(): {
+    config: CommentConfig;
+    threads: Thread[];
+    commentsByThread: Record<string, Comment[]>;
+    isLoading: boolean;
+    error: Error | null;
+    createThread: (anchor: ThreadAnchor, initialCommentBody?: string, initialAuthorName?: string | null) => Promise<Thread>;
+    loadComments: (threadId: string) => Promise<void>;
+    addComment: (threadId: string, body: string, authorName?: string | null) => Promise<Comment>;
+    deleteThread: (threadId: string) => Promise<void>;
+};
+
+type AuthUser = Pick<User, "id" | "email">;
+type AuthContextValue = {
+    supabase: SupabaseClient | null;
+    user: AuthUser | null;
+    accessToken: string | null;
+    isReady: boolean;
+    /** Resolved from GitHub: full_name, or username if name not set. Read-only. */
+    displayName: string;
+    signInWithEmail: (email: string) => Promise<void>;
+    signInWithGitHub: () => Promise<void>;
+    signOut: () => Promise<void>;
+};
+
+declare function useCommentAuth(): AuthContextValue;
+
+export { type CommentConfig, CommentOverlay, type CommentOverlayProps, CommentProvider, type CommentProviderProps, CommentSettings, CommentSurface, type CommentSurfaceProps, useCommentAuth, useComments };