@conexus-x/next-view 1.0.2 → 1.0.4

package/.env

@@ -1,21 +1,31 @@
 # ---------------------------------------------------------------------------
-# DEVELOPER MODE. None of this is used by your view in production.
+# DEVELOPER MODE ONLY — none of this ships with your extension.
 #
-# The values here power the dev preview at /dev, which frames your view the way
-# a Conexus X board does and feeds it REAL data from your workspace.
+# A deployed view holds no key and picks no workspace. It is framed by a board,
+# and the board tells it which workspace it is in and who is looking at it. The
+# values here exist so you can build against real data before that happens.
 # ---------------------------------------------------------------------------
 
-# Your Conexus X API key. Find it in the app under Settings > API.
+# Your Conexus X API key — find it in the app under Developer > API Key.
 #
-# It is read by the dev server ONLY and never reaches the browser: requests go
-# to /api/conexus/* on this app, which attaches the key server-side and forwards
-# them. A permanent credential in client-side JavaScript is a permanent
-# credential in every browser devtools panel that ever opens your view.
+# Read by the dev server ONLY; it never reaches the browser. A permanent
+# credential in client-side JavaScript is one devtools panel away from being
+# somebody else's.
 API_KEY=Conexus_x_api_key
 
+# The workspace this extension is built for.
+#
+# An extension is written against a SHAPE — particular boards, particular
+# columns — and every workspace holds different ones, so a view built for one
+# is meaningless pointed at another. Naming it here makes the dev page show
+# that workspace's boards and nothing else.
+#
+# Leave it blank the first time: the dev page then lists your workspaces with
+# their ids so you can copy one in.
+WORKSPACE_ID=
+
 # Where the Conexus X API lives.
 CONEXUS_API_URL=http://localhost:4040/api
 
 # Which origins may frame this view, space or comma separated.
-# Add your tunnel's CRM origin here when previewing inside the real app.
 CONEXUS_ORIGINS=http://localhost:3000 https://conexus-x.vercel.app

package/README.md

@@ -28,33 +28,43 @@ Nothing in this repo records the link, which is the point.
 
 ## Developer mode
 
-You do not need a Conexus X board to start. Put your API key in `.env` and open
-the developer page — it lists the workspaces that key can see, which is the
-shortest proof that your key works and the API is reachable.
+An extension is built for **one workspace**. Every workspace holds different
+boards and different columns, so a view written for Sales is meaningless
+pointed at Marketing — you name the one you mean, once, in `.env`.
 
 ```bash
-# .env — already in your project, just fill it in
-API_KEY=Conexus_x_api_key          # <- replace with your key (Settings > API)
-CONEXUS_API_URL=http://localhost:4040/api
+# .env — the only env file in this project. Fill in two values.
+API_KEY=Conexus_x_api_key   # <- your key: Conexus X > Developer > API Key
+WORKSPACE_ID=               # <- leave blank the first time
 ```
 
 ```bash
 npm run dev
 ```
 
-Then open **http://localhost:5173/dev**.
+Open **http://localhost:5173/dev**.
 
-**The key never reaches the browser.** The page is a React Server Component: `API_KEY` is read in Node and only the finished list is sent to the browser.
+With `WORKSPACE_ID` blank it lists your workspaces **with their ids**. Copy the
+one you are building for into `.env`, reload, and the page then shows that
+workspace and its boards — and only those.
+
+**The pin is development only, and it has to be.** In production the board
+decides which workspace your view is mounted in and hands it over as context. A
+view that chose its own workspace would be a view that could read one it was
+never mounted in. This page mirrors what the host will give you; it does not
+override it.
+
+**The key never reaches the browser.** The dev page is a React Server Component: `API_KEY` is read in Node and only the finished list is sent down.
 A permanent credential in client-side JavaScript is one devtools panel away
 from being somebody else's.
 
-`.env` is gitignored, so your real key cannot be committed by accident. The
-committed copy is `.env.example`.
+`.env` is gitignored, so your real key cannot be committed by accident — and it
+still ships inside the npm package, so a scaffolded project always has one
+ready to fill in.
 
-The developer page is not part of a production build, and **your view never
-uses the API key** — a deployed view receives data through the SDK, with the
-permissions of whoever is looking at the board. The key is scaffolding for
-development only.
+The dev page is not part of a production build, and **your view never uses the
+API key**: a deployed view receives data through the SDK, with the permissions
+of whoever is looking at the board.
 
 ## Previewing inside the real CRM
 

package/app/dev/AddBoardForm.tsx

@@ -0,0 +1,44 @@
+"use client";
+
+import { useActionState } from "react";
+
+import { createBoard, type CreateBoardState } from "./actions";
+
+const initialState: CreateBoardState = { error: null };
+
+/**
+ * Add a board to the pinned workspace, without leaving this page.
+ *
+ * `useActionState` gives the pending state and the returned error for free —
+ * the action itself does the actual POST, entirely on the server (see
+ * actions.ts). This form never sees the API key.
+ */
+export default function AddBoardForm({ workspaceId }: { workspaceId: string }) {
+    const [state, formAction, pending] = useActionState(createBoard, initialState);
+
+    return (
+        <form action={formAction} className="mb-4 flex items-center gap-2">
+            <input type="hidden" name="workspaceId" value={workspaceId} />
+
+            <input
+                name="name"
+                placeholder="New board name"
+                required
+                disabled={pending}
+                className="min-w-0 flex-1 rounded-lg border border-line bg-card px-3 py-1.5 text-[13px] outline-none transition placeholder:text-muted focus:border-accent disabled:opacity-60"
+            />
+
+            <button
+                type="submit"
+                disabled={pending}
+                className="shrink-0 rounded-lg bg-accent px-3 py-1.5 text-[13px] font-medium text-white transition hover:bg-accent-hover disabled:cursor-not-allowed disabled:opacity-60"
+            >
+                {pending ? "Adding…" : "Add board"}
+            </button>
+
+            {state.error ? (
+                <span className="text-[12px] text-danger">{state.error}</span>
+            ) : null}
+        </form>
+    );
+}

package/app/dev/CopyId.tsx

@@ -0,0 +1,30 @@
+"use client";
+
+import { useState } from "react";
+
+/**
+ * Copies a workspace or board id.
+ *
+ * The one piece of this page that has to run in the browser — clipboard access
+ * has no server-side equivalent — so it is its own tiny client component rather
+ * than turning the whole page client-side and losing the guarantee that the
+ * API key never ships to the browser.
+ */
+export default function CopyId({ value }: { value: string }) {
+    const [copied, setCopied] = useState(false);
+
+    return (
+        <button
+            type="button"
+            onClick={async () => {
+                await navigator.clipboard.writeText(value);
+                setCopied(true);
+                setTimeout(() => setCopied(false), 1500);
+            }}
+            title={copied ? "Copied" : `Copy ${value}`}
+            className="shrink-0 rounded-md border border-line px-2 py-0.5 font-mono text-[11px] text-muted transition hover:border-accent hover:text-accent"
+        >
+            {copied ? "Copied" : value}
+        </button>
+    );
+}

package/app/dev/actions.ts

@@ -0,0 +1,73 @@
+"use server";
+
+/**
+ * The one write the developer page needs: creating a board.
+ *
+ * A SERVER ACTION, for the same reason page.tsx is a Server Component — the
+ * function body, including every reference to `process.env.API_KEY`, stays on
+ * the server. Next compiles the client side down to an action id plus a
+ * dispatcher; the key it captures is never serialised into that reference.
+ * See node_modules/next/dist/docs/01-app/02-guides/server-actions.md
+ * "Closure variable encryption" for the mechanism this relies on.
+ *
+ * Deliberately the ONLY write on this page. Renaming or deleting a board from
+ * a debug screen is a bigger blast radius than a debug screen should carry —
+ * creating one is reversible in one click from Conexus X itself.
+ */
+
+import { revalidatePath } from "next/cache";
+
+const PLACEHOLDER = "Conexus_x_api_key";
+
+export interface CreateBoardState {
+    error: string | null;
+}
+
+export async function createBoard(
+    _previous: CreateBoardState,
+    formData: FormData
+): Promise<CreateBoardState> {
+    const apiKey = process.env.API_KEY;
+    const workspaceId = String(formData.get("workspaceId") ?? "").trim();
+    const name = String(formData.get("name") ?? "").trim();
+
+    if (!apiKey || apiKey === PLACEHOLDER) {
+        return { error: "API_KEY in .env is missing or still the placeholder." };
+    }
+
+    if (!workspaceId) {
+        return { error: "No workspace is pinned. Set WORKSPACE_ID in .env first." };
+    }
+
+    if (!name) {
+        return { error: "Give the board a name." };
+    }
+
+    const apiUrl = (process.env.CONEXUS_API_URL ?? "http://localhost:4040/api").replace(/\/$/, "");
+
+    try {
+        const response = await fetch(`${apiUrl}/modules/${workspaceId}`, {
+            method: "POST",
+            headers: {
+                "x-api-key": apiKey,
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify({ name })
+        });
+
+        if (!response.ok) {
+            const detail = await response.text();
+            return { error: `The API answered ${response.status}: ${detail.slice(0, 200)}` };
+        }
+    } catch (error) {
+        return {
+            error: `Could not reach the API — ${error instanceof Error ? error.message : String(error)}`
+        };
+    }
+
+    // Re-renders /dev with the fresh board list, in the SAME response as this
+    // action — the developer sees the new board without a manual reload.
+    revalidatePath("/dev");
+
+    return { error: null };
+}

package/app/dev/page.tsx

@@ -1,23 +1,30 @@
 import { notFound } from "next/navigation";
 
+import AddBoardForm from "./AddBoardForm";
+import CopyId from "./CopyId";
+
 /**
  * DEVELOPER MODE — http://localhost:5173/dev
  *
- * Put your API key in .env, reload, and this lists the workspaces that key can
- * see. It is the shortest possible proof that your key works and the API is
- * reachable, which is the thing that is actually wrong the first time nothing
- * renders.
+ * Put your API key and the workspace you are building for in .env, reload, and
+ * this shows that workspace's boards. It is the shortest proof that your key
+ * works, the API is reachable, and you are pointed at the right data — which is
+ * what is actually wrong the first time nothing renders.
  *
- * A SERVER COMPONENT, deliberately. The key is read here, in Node, and only the
- * finished list is sent to the browser — so the key never appears in a bundle,
- * a network tab, or anybody's devtools. Fetching this from the browser would
- * put a permanent credential in client-side JavaScript, and a permanent
- * credential in client-side JavaScript is one screenshot away from being
- * somebody else's.
+ * WHY A WORKSPACE IS PINNED IN .env: an extension is written against a SHAPE —
+ * particular boards, particular columns — and every workspace holds different
+ * ones. A view built for Sales is meaningless pointed at Marketing, so the
+ * developer names the one they mean instead of browsing all of them.
+ *
+ * THAT PIN IS DEVELOPMENT ONLY, and it has to be. In production the BOARD
+ * decides which workspace a view is mounted in and hands it over as context; a
+ * view that chose its own would be a view that could read a workspace it was
+ * never mounted in. This file mirrors what the host will hand you. It does not
+ * override it.
  *
- * Your VIEW does not work this way and must not: it runs framed by a board and
- * receives data through the SDK, with the signed-in person's own permissions.
- * This page is scaffolding for development, nothing more.
+ * A SERVER COMPONENT, deliberately. The key is read here, in Node, and only the
+ * finished list is sent to the browser — so it never appears in a bundle, a
+ * network tab, or anybody's devtools.
  */
 
 // Never prerendered: it reads .env and the network at request time.
@@ -25,74 +32,112 @@ export const dynamic = "force-dynamic";
 
 const PLACEHOLDER = "Conexus_x_api_key";
 
+interface Workspace {
+    _id: string;
+    name?: string;
+    totalModules?: number;
+}
+
 interface WorkspaceMembership {
     _id: string;
     role?: string;
-    status?: string;
-    workspace?: {
-        _id: string;
-        name?: string;
-        description?: string;
-        totalModules?: number;
-    } | null;
+    workspace?: Workspace | null;
 }
 
-type LoadResult =
-    | { ok: true; workspaces: WorkspaceMembership[] }
-    | { ok: false; title: string; detail: string };
+interface Board {
+    _id: string;
+    name?: string;
+    description?: string;
+    visibility?: string;
+    totalRecords?: number;
+}
 
-const loadWorkspaces = async (): Promise<LoadResult> => {
+type DevState =
+    | { kind: "error"; title: string; detail: string }
+    /** No WORKSPACE_ID yet — show what is available so one can be copied in. */
+    | { kind: "pick"; workspaces: WorkspaceMembership[] }
+    | { kind: "pinned"; workspace: Workspace; role: string | undefined; boards: Board[] };
+
+const apiUrl = () =>
+    (process.env.CONEXUS_API_URL ?? "http://localhost:4040/api").replace(/\/$/, "");
+
+const load = async (): Promise<DevState> => {
     const apiKey = process.env.API_KEY;
-    const apiUrl = (process.env.CONEXUS_API_URL ?? "http://localhost:4040/api").replace(/\/$/, "");
+    const workspaceId = (process.env.WORKSPACE_ID ?? "").trim();
 
     if (!apiKey) {
         return {
-            ok: false,
+            kind: "error",
             title: "No API key",
-            detail: "Add API_KEY to .env in this project, then reload."
+            detail: "Add API_KEY to .env in this project, then reload.",
         };
     }
 
     if (apiKey === PLACEHOLDER) {
         return {
-            ok: false,
+            kind: "error",
             title: "The API key is still the placeholder",
-            detail: `Replace API_KEY=${PLACEHOLDER} in .env with your own key from Conexus X (Settings › API), then reload.`
+            detail: `Replace API_KEY=${PLACEHOLDER} in .env with your own key from Conexus X (Developer › API Key), then reload.`,
         };
     }
 
-    try {
-        const response = await fetch(`${apiUrl}/workspaces`, {
+    const call = async (path: string) => {
+        const response = await fetch(`${apiUrl()}${path}`, {
             headers: { "x-api-key": apiKey },
-            cache: "no-store"
+            cache: "no-store",
         });
 
         if (response.status === 401) {
-            return {
-                ok: false,
-                title: "That key was rejected",
-                detail: "The API answered 401. Check the key, and that the account it belongs to is still active."
-            };
+            throw new Error(
+                "The API answered 401. Check the key, and that the account it belongs to is still active."
+            );
         }
 
         if (!response.ok) {
+            throw new Error(`The API answered ${response.status}: ${(await response.text()).slice(0, 200)}`);
+        }
+
+        return response.json() as Promise<Record<string, unknown>>;
+    };
+
+    try {
+        const body = await call("/workspaces");
+        const memberships = (body["workspaces"] as WorkspaceMembership[] | undefined) ?? [];
+
+        if (!workspaceId) {
+            return { kind: "pick", workspaces: memberships };
+        }
+
+        const mine = memberships.find((row) => row.workspace?._id === workspaceId);
+
+        // A pinned id that is not one of yours is the single most confusing
+        // failure here — every call succeeds and the page is simply empty — so
+        // it is named rather than left to look like "no boards".
+        if (!mine?.workspace) {
             return {
-                ok: false,
-                title: `The API answered ${response.status}`,
-                detail: (await response.text()).slice(0, 300)
+                kind: "error",
+                title: "WORKSPACE_ID does not match a workspace you are in",
+                detail:
+                    `.env points at ${workspaceId}, which is not among the ${memberships.length} ` +
+                    "workspace(s) this key can see. Clear WORKSPACE_ID to list them again.",
             };
         }
 
-        const body = (await response.json()) as { workspaces?: WorkspaceMembership[] };
+        const boardsBody = await call(`/modules/${workspaceId}`);
 
-        return { ok: true, workspaces: body.workspaces ?? [] };
+        return {
+            kind: "pinned",
+            workspace: mine.workspace,
+            role: mine.role,
+            boards: (boardsBody["modules"] as Board[] | undefined) ?? [],
+        };
     } catch (error) {
         return {
-            ok: false,
+            kind: "error",
             title: "Could not reach the API",
             detail:
-                `Tried ${apiUrl}/workspaces — ${error instanceof Error ? error.message : String(error)}. ` +
-                "Is the Conexus X API running, and is CONEXUS_API_URL right?"
+                `${error instanceof Error ? error.message : String(error)}\n\n` +
+                `Tried ${apiUrl()}. Is the Conexus X API running, and is CONEXUS_API_URL right?`,
         };
     }
 };
@@ -102,60 +147,131 @@ export default async function DevPage() {
     // business in a deployed view, so it is not there.
     if (process.env.NODE_ENV === "production") notFound();
 
-    const result = await loadWorkspaces();
+    const state = await load();
 
     return (
         <main className="mx-auto max-w-2xl p-6">
             <header className="mb-5">
                 <h1 className="text-lg font-semibold">Developer mode</h1>
                 <p className="mt-1 text-[13px] text-muted">
-                    Workspaces visible to the API key in <code>.env</code>.
+                    {state.kind === "pinned"
+                        ? "The workspace this extension is built for, and its boards."
+                        : "Reading the API key in .env."}
                 </p>
             </header>
 
-            {!result.ok ? (
+            {state.kind === "error" ? (
                 <div className="rounded-lg border border-danger bg-danger-soft px-4 py-3 text-danger">
-                    <strong className="font-semibold">{result.title}</strong>
-                    <p className="mt-1.5 text-[13px] whitespace-pre-wrap">{result.detail}</p>
+                    <strong className="font-semibold">{state.title}</strong>
+                    <p className="mt-1.5 text-[13px] whitespace-pre-wrap">{state.detail}</p>
                 </div>
-            ) : result.workspaces.length === 0 ? (
-                <p className="text-[13px] text-muted">
-                    The key works — this account is not a member of any workspace yet.
-                </p>
+            ) : state.kind === "pick" ? (
+                <>
+                    <div className="mb-4 rounded-lg border border-line bg-accent-soft px-4 py-3">
+                        <strong className="font-semibold">Pick the workspace you are building for</strong>
+                        <p className="mt-1 text-[13px]">
+                            Copy its id into <code>WORKSPACE_ID</code> in <code>.env</code> and
+                            reload. This view will then show that workspace&apos;s boards — and
+                            only those.
+                        </p>
+                    </div>
+
+                    {state.workspaces.length === 0 ? (
+                        <p className="text-[13px] text-muted">
+                            The key works — this account is not a member of any workspace yet.
+                        </p>
+                    ) : (
+                        <ul className="rounded-lg border border-line">
+                            {state.workspaces.map((membership) => (
+                                <li
+                                    key={membership._id}
+                                    className="flex items-center gap-3 border-b border-line px-4 py-3 last:border-b-0"
+                                >
+                                    <div className="min-w-0 flex-1">
+                                        <div className="truncate font-medium">
+                                            {membership.workspace?.name ?? "Untitled workspace"}
+                                        </div>
+                                    </div>
+
+                                    {membership.workspace?._id ? (
+                                        <CopyId value={membership.workspace._id} />
+                                    ) : null}
+
+                                    {membership.role ? (
+                                        <span className="shrink-0 rounded-md border border-line px-2 py-0.5 text-[12px] text-muted">
+                                            {membership.role}
+                                        </span>
+                                    ) : null}
+
+                                    <span className="shrink-0 text-[12px] text-muted">
+                                        {membership.workspace?.totalModules ?? 0} boards
+                                    </span>
+                                </li>
+                            ))}
+                        </ul>
+                    )}
+                </>
             ) : (
-                <ul className="rounded-lg border border-line">
-                    {result.workspaces.map((membership) => (
-                        <li
-                            key={membership._id}
-                            className="flex items-center gap-3 border-b border-line px-4 py-3 last:border-b-0"
-                        >
-                            <div className="min-w-0 flex-1">
-                                <div className="truncate font-medium">
-                                    {membership.workspace?.name ?? "Untitled workspace"}
-                                </div>
-                                <div className="mt-0.5 font-mono text-[12px] text-muted">
-                                    {membership.workspace?._id}
-                                </div>
+                <>
+                    <div className="mb-4 flex items-center gap-3 rounded-lg border border-line px-4 py-3">
+                        <div className="min-w-0 flex-1">
+                            <div className="truncate text-[15px] font-semibold">
+                                {state.workspace.name ?? "Untitled workspace"}
                             </div>
+                        </div>
 
-                            {membership.role ? (
-                                <span className="shrink-0 rounded-md border border-line px-2 py-0.5 text-[12px] text-muted">
-                                    {membership.role}
-                                </span>
-                            ) : null}
+                        <CopyId value={state.workspace._id} />
 
-                            <span className="shrink-0 text-[12px] text-muted">
-                                {membership.workspace?.totalModules ?? 0} boards
+                        {state.role ? (
+                            <span className="shrink-0 rounded-md border border-line px-2 py-0.5 text-[12px] text-muted">
+                                {state.role}
                             </span>
-                        </li>
-                    ))}
-                </ul>
+                        ) : null}
+                    </div>
+
+                    <AddBoardForm workspaceId={state.workspace._id} />
+
+                    {state.boards.length === 0 ? (
+                        <p className="text-[13px] text-muted">
+                            This workspace has no boards yet. Create one in Conexus X and
+                            reload.
+                        </p>
+                    ) : (
+                        <ul className="rounded-lg border border-line">
+                            {state.boards.map((board) => (
+                                <li
+                                    key={board._id}
+                                    className="flex items-center gap-3 border-b border-line px-4 py-3 last:border-b-0"
+                                >
+                                    <div className="min-w-0 flex-1">
+                                        <div className="truncate font-medium">
+                                            {board.name ?? "Untitled board"}
+                                        </div>
+                                    </div>
+
+.0000000000000000000000000000000000000000000000000000000000000000006+++++++++++++++++++++++++++++++++++++++++++++++++++++++++4
+                                    <CopyId value={board._id} />
+
+                                    {board.visibility ? (
+                                        <span className="shrink-0 rounded-md border border-line px-2 py-0.5 text-[12px] text-muted">
+                                            {board.visibility}
+                                        </span>
+                                    ) : null}
+
+                                    <span className="shrink-0 text-[12px] text-muted">
+                                        {board.totalRecords ?? 0} records
+                                    </span>
+                                </li>
+                            ))}
+                        </ul>
+                    )}
+                </>
             )}
 
             <p className="mt-5 text-[12px] text-muted">
-                This page is development-only and returns 404 in a production build.
-                Your view itself never uses the API key — it receives data through
-                the SDK, with the permissions of whoever is looking at the board.
+                Development-only, and returns 404 in a production build. Your view itself
+                never uses the API key and never chooses a workspace — the board it is
+                mounted in tells it which one, with the permissions of whoever is looking.
             </p>
         </main>
     );

package/app/page.tsx

@@ -3,13 +3,20 @@
 /**
  * The starter view.
  *
- * Lists the records in whichever collection the person is looking at, lets them
- * tick one complete, and stays live while colleagues edit the same board. It is
- * the smallest thing that exercises every part of the SDK worth knowing:
- * context, a scoped read, a scoped write, host chrome, and realtime.
+ * It renders WHATEVER THE HOST GAVE IT, which is the single most important
+ * thing to copy from this file:
  *
- * Note what is NOT here: no fetch, no API base URL, no token, no socket. The
- * host owns all four, which is why this file is short.
+ *   mounted on a workspace  -> the boards in that workspace
+ *   mounted on a board      -> the records in the collection in view
+ *
+ * The first version only ever listed records, so a view mounted at workspace
+ * level — which is what the CRM preview does — sat there saying "open a
+ * collection" and looked broken. A view must read `context` and show what is
+ * actually there.
+ *
+ * Note what is NOT here: no fetch, no API base URL, no token, no socket, and no
+ * workspace id of its own. The host owns all of it and hands over context with
+ * the permissions of whoever is looking, which is why this file is short.
  *
  * Styling is Tailwind, already configured — see app/globals.css. The colour
  * names (`bg-card`, `text-muted`, `border-line`) flip with the board's theme on
@@ -20,6 +27,7 @@ import {
     useAutoResize,
     useCommands,
     useConnection,
+    useModules,
     useRecords,
     useScope,
     useSettings,
@@ -34,6 +42,10 @@ interface ViewSettings {
     showCompleted?: boolean;
 }
 
+const Skeleton = () => (
+    <div className="h-3.5 w-full animate-pulse rounded bg-line" />
+);
+
 export default function View() {
     const { status, error } = useConnection();
     const context = useViewContext();
@@ -49,12 +61,20 @@ export default function View() {
      * settings receives an empty object.
      */
     const settings = useSettings<ViewSettings>();
-    const title = settings.title ?? "Records";
     const showCompleted = settings.showCompleted ?? true;
 
+    /**
+     * Both queries are declared, and only the applicable one runs.
+     *
+     * Each is disabled when its id is missing, so the board list costs nothing
+     * on a board-level mount and the record list costs nothing above one. Hooks
+     * cannot be called conditionally; queries can be skipped.
+     */
+    const boards = useModules(context?.collectionId ? undefined : context?.workspaceId);
+
     const {
         data: records,
-        loading,
+        loading: recordsLoading,
         error: recordsError,
         refresh
     } = useRecords(context?.collectionId);
@@ -86,6 +106,10 @@ export default function View() {
         );
     }
 
+    const onBoard = Boolean(context?.collectionId);
+    const title = settings.title ?? (onBoard ? "Records" : "Boards");
+    const failure = onBoard ? recordsError : boards.error;
+
     return (
         <main className="p-4">
             <ThemeSync theme={context?.theme ?? "light"} />
@@ -97,47 +121,76 @@ export default function View() {
                 </span>
             </header>
 
-            {!context?.collectionId ? (
-                <p className="text-[13px] text-muted">Open a collection to see its records.</p>
-            ) : recordsError ? (
+            {failure ? (
                 <div className="rounded-lg border border-danger bg-danger-soft px-3.5 py-3 text-danger">
-                    {recordsError.code === "scope_denied"
-                        ? "This app was not granted permission to read records."
-                        : recordsError.message}
+                    {failure.code === "scope_denied"
+                        ? `This app was not granted permission to read ${onBoard ? "records" : "boards"}.`
+                        : failure.message}
                 </div>
-            ) : loading && !records ? (
-                <div className="h-3.5 w-full animate-pulse rounded bg-line" />
+            ) : onBoard ? (
+                /* ---- mounted on a board: the records in view ---- */
+                recordsLoading && !records ? (
+                    <Skeleton />
+                ) : records?.length === 0 ? (
+                    <p className="text-[13px] text-muted">
+                        No records in this collection yet.
+                    </p>
+                ) : (
+                    <ul>
+                        {(records ?? [])
+                            .filter((record) => showCompleted || !record.isCompleted)
+                            .map((record) => (
+                                <RecordRow
+                                    key={record._id}
+                                    record={record}
+                                    canWrite={canWrite}
+                                    onOpen={() =>
+                                        commands
+                                            .openRecord(record._id)
+                                            .catch(() =>
+                                                commands.notice(
+                                                    "This board cannot open records from a view.",
+                                                    "info"
+                                                )
+                                            )
+                                    }
+                                    onError={(message) => {
+                                        void commands.notice(message, "error");
+                                        refresh();
+                                    }}
+                                />
+                            ))}
+                    </ul>
+                )
+            ) : /* ---- mounted on a workspace: the boards in it ---- */
+            boards.loading && !boards.data ? (
+                <Skeleton />
+            ) : boards.data?.length === 0 ? (
+                <p className="text-[13px] text-muted">
+                    This workspace has no boards yet.
+                </p>
             ) : (
                 <ul>
-                    {(records ?? [])
-                        .filter((record) => showCompleted || !record.isCompleted)
-                        .map((record) => (
-                            <RecordRow
-                                key={record._id}
-                                record={record}
-                                canWrite={canWrite}
-                                onOpen={() =>
-                                    commands
-                                        .openRecord(record._id)
-                                        .catch(() =>
-                                            commands.notice(
-                                                "This board cannot open records from a view.",
-                                                "info"
-                                            )
-                                        )
-                                }
-                                onError={(message) => {
-                                    void commands.notice(message, "error");
-                                    refresh();
-                                }}
-                            />
-                        ))}
+                    {(boards.data ?? []).map((board) => (
+                        <li
+                            key={board._id}
+                            className="flex items-center gap-2.5 border-b border-line py-2 last:border-b-0"
+                        >
+                            <span className="min-w-0 flex-1 truncate">{board.name}</span>
+
+                            {board.visibility && board.visibility !== "workspace" ? (
+                                <span className="shrink-0 rounded-md border border-line px-1.5 py-0.5 text-[11px] text-muted">
+                                    {board.visibility}
+                                </span>
+                            ) : null}
+
+                            <span className="shrink-0 text-[13px] text-muted">
+                                {board.totalRecords ?? 0} records
+                            </span>
+                        </li>
+                    ))}
                 </ul>
             )}
-
-            {records?.length === 0 && context?.collectionId ? (
-                <p className="text-[13px] text-muted">No records in this collection yet.</p>
-            ) : null}
         </main>
     );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@conexus-x/next-view",
-    "version": "1.0.2",
+    "version": "1.0.4",
     "private": false,
     "description": "Custom view for Conexus X — Next.js starter, wired to @conexus-x/sdk.",
     "scripts": {
@@ -11,7 +11,7 @@
         "tunnel": "npx -y cloudflared tunnel --url http://localhost:5173"
     },
     "dependencies": {
-        "@conexus-x/sdk": "^0.1.0",
+        "@conexus-x/sdk": "^0.1.2",
         "next": "16.2.10",
         "react": "19.2.4",
         "react-dom": "19.2.4"
@@ -35,7 +35,6 @@
         "tsconfig.json",
         "conexus.manifest.json",
         ".env",
-        ".env.example",
         "README.md",
         ".gitignore"
     ]

package/.env.example

@@ -1,21 +0,0 @@
-# ---------------------------------------------------------------------------
-# DEVELOPER MODE. None of this is used by your view in production.
-#
-# The values here power the dev preview at /dev, which frames your view the way
-# a Conexus X board does and feeds it REAL data from your workspace.
-# ---------------------------------------------------------------------------
-
-# Your Conexus X API key. Find it in the app under Settings > API.
-#
-# It is read by the dev server ONLY and never reaches the browser: requests go
-# to /api/conexus/* on this app, which attaches the key server-side and forwards
-# them. A permanent credential in client-side JavaScript is a permanent
-# credential in every browser devtools panel that ever opens your view.
-API_KEY=Conexus_x_api_key
-
-# Where the Conexus X API lives.
-CONEXUS_API_URL=http://localhost:4040/api
-
-# Which origins may frame this view, space or comma separated.
-# Add your tunnel's CRM origin here when previewing inside the real app.
-CONEXUS_ORIGINS=http://localhost:3000 https://conexus-x.vercel.app