From be5ed18db0447845377cb6e7e9754523237e12e4 Mon Sep 17 00:00:00 2001
From: Steve Dudenhoeffer <steve@stevedudenhoeffer.com>
Date: Sat, 18 Jul 2026 23:57:59 -0400
Subject: [PATCH] Add sharing UI: invite by email, roles, read-only viewer mode
 (#17)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- lib/shares.ts: zod Share shape + hooks (useShares/useAddShare/
  useUpdateShareRole/useRemoveShare over /gardens/:id/shares).
- lib/gardens.ts: myRole on the garden schema + canEditRole/isOwnerRole helpers
  (role always comes from the server's my_role, never guessed).
- ShareGardenModal (owner only): invite an existing user by email as viewer/
  editor, change a share's role inline, remove; surfaces the backend's friendly
  "no account with that email". Reachable from the garden card and the editor.
- GardenCard: "shared · viewer/editor" badge on non-owned gardens; owner gets
  Share/Edit/Delete, a recipient gets Leave (LeaveGardenModal removes their own
  share).
- Read-only viewer mode in the editor, gated on a single canEdit flag:
  viewers get no palette, no select/move/resize/rotate handles, no plop overlay,
  no placement, and read-only inspectors (a disabled <fieldset> makes every field
  read-only in one shot; Change/Delete/Remove/Plant-here hidden), plus a "View
  only" indicator. Defense in depth: the canvas create/place handlers also check
  canEdit, so a missed gate can't fire a mutation that would 403.

tsc --noEmit clean; 24/24 vitest; production build green.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JdQpdYYsTgtkJBxbcpAszi
---
 web/src/components/gardens/GardenCard.tsx     |  59 ++++++---
 .../components/gardens/LeaveGardenModal.tsx   |  47 +++++++
 .../components/gardens/ShareGardenModal.tsx   | 121 ++++++++++++++++++
 web/src/editor/GardenCanvas.tsx               |  16 ++-
 web/src/editor/Inspector.tsx                  |  85 ++++++------
 web/src/editor/PlopInspector.tsx              |  56 ++++----
 web/src/lib/gardens.ts                        |  16 +++
 web/src/lib/shares.ts                         |  69 ++++++++++
 web/src/pages/GardenEditorPage.tsx            |  45 +++++--
 web/src/pages/GardensPage.tsx                 |  16 ++-
 10 files changed, 433 insertions(+), 97 deletions(-)
 create mode 100644 web/src/components/gardens/LeaveGardenModal.tsx
 create mode 100644 web/src/components/gardens/ShareGardenModal.tsx
 create mode 100644 web/src/lib/shares.ts

diff --git a/web/src/components/gardens/GardenCard.tsx b/web/src/components/gardens/GardenCard.tsx
index 61828f5..56f6f06 100644
--- a/web/src/components/gardens/GardenCard.tsx
+++ b/web/src/components/gardens/GardenCard.tsx
@@ -1,20 +1,33 @@
 import { Link } from '@tanstack/react-router'
-import type { Garden } from '@/lib/gardens'
+import { isOwnerRole, type Garden } from '@/lib/gardens'
 import { formatDimensions } from '@/lib/units'
 
+const actionClass =
+  'rounded-md px-2.5 py-1 text-sm font-medium text-muted outline-none transition-colors ' +
+  'hover:bg-border/50 hover:text-fg focus-visible:ring-2 focus-visible:ring-accent/40'
+const dangerClass =
+  'rounded-md px-2.5 py-1 text-sm font-medium text-muted outline-none transition-colors ' +
+  'hover:bg-red-500/10 hover:text-red-600 focus-visible:ring-2 focus-visible:ring-red-500/40 dark:hover:text-red-400'
+
 /**
- * One garden as a card: the body links into the editor (/gardens/:id); the
- * footer has edit/delete actions (kept out of the link so they don't navigate).
+ * One garden as a card: the body links into the editor. The footer differs by
+ * role — the owner gets Share / Edit / Delete; a recipient sees a "shared · role"
+ * badge and a Leave action (garden metadata edit + sharing are owner-only).
  */
 export function GardenCard({
   garden,
+  onShare,
   onEdit,
   onDelete,
+  onLeave,
 }: {
   garden: Garden
+  onShare: () => void
   onEdit: () => void
   onDelete: () => void
+  onLeave: () => void
 }) {
+  const owner = isOwnerRole(garden.myRole)
   return (
     <div className="flex flex-col rounded-xl border border-border bg-surface transition-colors hover:border-accent/50">
       <Link
@@ -22,27 +35,37 @@ export function GardenCard({
         params={{ gardenId: String(garden.id) }}
         className="flex-1 rounded-t-xl p-4 outline-none focus-visible:ring-2 focus-visible:ring-accent/40"
       >
-        <h3 className="truncate font-semibold text-fg">{garden.name}</h3>
+        <div className="flex items-center gap-2">
+          <h3 className="truncate font-semibold text-fg">{garden.name}</h3>
+          {!owner && garden.myRole && (
+            <span className="shrink-0 rounded bg-border/60 px-1.5 py-0.5 text-[10px] font-medium uppercase tracking-wide text-muted">
+              shared · {garden.myRole}
+            </span>
+          )}
+        </div>
         <p className="mt-1 text-sm text-muted">
           {formatDimensions(garden.widthCm, garden.heightCm, garden.unitPref)}
         </p>
         {garden.notes && <p className="mt-2 line-clamp-2 text-sm text-muted">{garden.notes}</p>}
       </Link>
       <div className="flex justify-end gap-1 border-t border-border px-2 py-1.5">
-        <button
-          type="button"
-          onClick={onEdit}
-          className="rounded-md px-2.5 py-1 text-sm font-medium text-muted outline-none transition-colors hover:bg-border/50 hover:text-fg focus-visible:ring-2 focus-visible:ring-accent/40"
-        >
-          Edit
-        </button>
-        <button
-          type="button"
-          onClick={onDelete}
-          className="rounded-md px-2.5 py-1 text-sm font-medium text-muted outline-none transition-colors hover:bg-red-500/10 hover:text-red-600 focus-visible:ring-2 focus-visible:ring-red-500/40 dark:hover:text-red-400"
-        >
-          Delete
-        </button>
+        {owner ? (
+          <>
+            <button type="button" onClick={onShare} className={actionClass}>
+              Share
+            </button>
+            <button type="button" onClick={onEdit} className={actionClass}>
+              Edit
+            </button>
+            <button type="button" onClick={onDelete} className={dangerClass}>
+              Delete
+            </button>
+          </>
+        ) : (
+          <button type="button" onClick={onLeave} className={dangerClass}>
+            Leave
+          </button>
+        )}
       </div>
     </div>
   )
diff --git a/web/src/components/gardens/LeaveGardenModal.tsx b/web/src/components/gardens/LeaveGardenModal.tsx
new file mode 100644
index 0000000..85c9dce
--- /dev/null
+++ b/web/src/components/gardens/LeaveGardenModal.tsx
@@ -0,0 +1,47 @@
+import { useState } from 'react'
+import { Modal } from '@/components/ui/Modal'
+import { Alert } from '@/components/ui/Alert'
+import { Button } from '@/components/ui/Button'
+import { errorMessage } from '@/lib/api'
+import { useMe } from '@/lib/auth'
+import type { Garden } from '@/lib/gardens'
+import { useRemoveShare } from '@/lib/shares'
+
+/** Confirmation for a recipient leaving a garden shared with them (removes their
+ *  own share). */
+export function LeaveGardenModal({ garden, onClose }: { garden: Garden; onClose: () => void }) {
+  const me = useMe()
+  const remove = useRemoveShare(garden.id)
+  const [error, setError] = useState<string | null>(null)
+
+  async function onConfirm() {
+    if (!me.data) return
+    setError(null)
+    try {
+      await remove.mutateAsync(me.data.id)
+      onClose()
+    } catch (err) {
+      setError(errorMessage(err, 'Could not leave the garden.'))
+    }
+  }
+
+  return (
+    <Modal title="Leave garden" onClose={onClose} busy={remove.isPending}>
+      <div className="flex flex-col gap-4">
+        <p className="text-sm text-muted">
+          Leave <span className="font-medium text-fg">{garden.name}</span>? You'll lose access until the owner
+          shares it with you again.
+        </p>
+        {error && <Alert>{error}</Alert>}
+        <div className="flex justify-end gap-2">
+          <Button type="button" variant="ghost" onClick={onClose} disabled={remove.isPending}>
+            Cancel
+          </Button>
+          <Button type="button" variant="danger" onClick={onConfirm} disabled={remove.isPending || !me.data}>
+            {remove.isPending ? 'Leaving…' : 'Leave'}
+          </Button>
+        </div>
+      </div>
+    </Modal>
+  )
+}
diff --git a/web/src/components/gardens/ShareGardenModal.tsx b/web/src/components/gardens/ShareGardenModal.tsx
new file mode 100644
index 0000000..c9c6bf1
--- /dev/null
+++ b/web/src/components/gardens/ShareGardenModal.tsx
@@ -0,0 +1,121 @@
+import { useState, type FormEvent } from 'react'
+import { Modal } from '@/components/ui/Modal'
+import { Alert } from '@/components/ui/Alert'
+import { Button } from '@/components/ui/Button'
+import { Select } from '@/components/ui/Select'
+import { TextField } from '@/components/ui/TextField'
+import { cn } from '@/lib/cn'
+import { fieldControlClass } from '@/components/ui/field'
+import { errorMessage } from '@/lib/api'
+import type { Garden } from '@/lib/gardens'
+import { useAddShare, useRemoveShare, useShares, useUpdateShareRole, type ShareRole } from '@/lib/shares'
+
+const roleOptions = [
+  { value: 'viewer', label: 'Viewer (read-only)' },
+  { value: 'editor', label: 'Editor (can edit)' },
+]
+
+/**
+ * Owner-only dialog to manage a garden's shares: invite an existing user by
+ * email as viewer/editor, change a share's role, or remove it. Targets existing
+ * accounts only (v1 has no invitation emails) — an unknown email surfaces a
+ * friendly "no account with that email".
+ */
+export function ShareGardenModal({ garden, onClose }: { garden: Garden; onClose: () => void }) {
+  const shares = useShares(garden.id)
+  const add = useAddShare(garden.id)
+  const updateRole = useUpdateShareRole(garden.id)
+  const remove = useRemoveShare(garden.id)
+
+  const [email, setEmail] = useState('')
+  const [role, setRole] = useState<ShareRole>('viewer')
+  const [error, setError] = useState<string | null>(null)
+
+  async function onInvite(e: FormEvent) {
+    e.preventDefault()
+    setError(null)
+    if (!email.trim()) {
+      setError('Enter an email address.')
+      return
+    }
+    try {
+      await add.mutateAsync({ email: email.trim(), role })
+      setEmail('')
+    } catch (err) {
+      setError(errorMessage(err, 'Could not share the garden.'))
+    }
+  }
+
+  return (
+    <Modal title="Share garden" onClose={onClose} busy={add.isPending}>
+      <div className="flex flex-col gap-4">
+        <form onSubmit={onInvite} className="flex flex-col gap-2">
+          <TextField
+            label="Invite by email"
+            name="email"
+            type="email"
+            placeholder="person@example.com"
+            value={email}
+            onChange={(e) => setEmail(e.target.value)}
+          />
+          <div className="flex items-end gap-2">
+            <Select
+              label="Role"
+              name="role"
+              value={role}
+              onChange={(e) => setRole(e.target.value as ShareRole)}
+              options={roleOptions}
+              className="flex-1"
+            />
+            <Button type="submit" disabled={add.isPending}>
+              {add.isPending ? 'Sharing…' : 'Share'}
+            </Button>
+          </div>
+          {error && <Alert>{error}</Alert>}
+        </form>
+
+        <div>
+          <h3 className="mb-2 text-sm font-medium text-fg">Shared with</h3>
+          {shares.isPending && <p className="text-sm text-muted">Loading…</p>}
+          {shares.isError && <Alert>Could not load who this garden is shared with.</Alert>}
+          {shares.isSuccess && shares.data.length === 0 && (
+            <p className="text-sm text-muted">Not shared with anyone yet.</p>
+          )}
+          <ul className="flex flex-col gap-2">
+            {shares.data?.map((sh) => (
+              <li key={sh.userId} className="flex items-center gap-2">
+                <div className="min-w-0 flex-1">
+                  <p className="truncate text-sm font-medium text-fg">{sh.displayName}</p>
+                  <p className="truncate text-xs text-muted">{sh.email}</p>
+                </div>
+                <select
+                  value={sh.role}
+                  onChange={(e) => updateRole.mutate({ userId: sh.userId, role: e.target.value as ShareRole })}
+                  aria-label={`Role for ${sh.displayName}`}
+                  className={cn(fieldControlClass, 'w-auto px-2 py-1 text-sm')}
+                >
+                  <option value="viewer">Viewer</option>
+                  <option value="editor">Editor</option>
+                </select>
+                <button
+                  type="button"
+                  onClick={() => remove.mutate(sh.userId)}
+                  aria-label={`Remove ${sh.displayName}`}
+                  className="rounded-md px-2 py-1 text-sm text-muted transition-colors hover:bg-red-500/10 hover:text-red-600 dark:hover:text-red-400"
+                >
+                  ✕
+                </button>
+              </li>
+            ))}
+          </ul>
+        </div>
+
+        <div className="flex justify-end">
+          <Button variant="ghost" onClick={onClose}>
+            Done
+          </Button>
+        </div>
+      </div>
+    </Modal>
+  )
+}
diff --git a/web/src/editor/GardenCanvas.tsx b/web/src/editor/GardenCanvas.tsx
index 5b27758..ca23c68 100644
--- a/web/src/editor/GardenCanvas.tsx
+++ b/web/src/editor/GardenCanvas.tsx
@@ -34,11 +34,13 @@ export function GardenCanvas({
   objects,
   plantings,
   plantsById,
+  canEdit,
 }: {
   garden: EditorGarden
   objects: EditorObject[]
   plantings: EditorPlanting[]
   plantsById: Map<number, Plant>
+  canEdit: boolean
 }) {
   const svgRef = useRef<SVGSVGElement>(null)
   const containerRef = useRef<HTMLDivElement>(null)
@@ -108,7 +110,9 @@ export function GardenCanvas({
   // or exit focus mode, or just deselect.
   function onCanvasPointerDown(e: ReactPointerEvent) {
     const armed = useEditorStore.getState().armedKind
-    if (armed) {
+    // Defense in depth: a viewer can't place objects even if a stale armed kind
+    // slipped through (the palette isn't rendered for them).
+    if (armed && canEdit) {
       useEditorStore.getState().setArmedKind(null)
       const def = kindDef(armed)
       const rect = svgRef.current?.getBoundingClientRect()
@@ -134,7 +138,7 @@ export function GardenCanvas({
   // armed for repeat-placement until Escape / Done).
   function onPlace(e: ReactPointerEvent) {
     e.stopPropagation()
-    if (!focusedObject || !armedPlant || !focusedObject.plantable) return
+    if (!canEdit || !focusedObject || !armedPlant || !focusedObject.plantable) return
     const rect = svgRef.current?.getBoundingClientRect()
     if (!rect) return
     const world = screenToWorld({ x: e.clientX - rect.left, y: e.clientY - rect.top }, viewport)
@@ -188,14 +192,16 @@ export function GardenCanvas({
             onSelectPlop={selectPlanting}
           />
 
-          {selectedObject && <SelectionOverlay object={selectedObject} gardenId={garden.id} svgRef={svgRef} />}
-          {selectedPlop && selectedPlopObject && (
+          {/* Edit handles are mounted only for editors/owners; viewers can still
+              select to inspect (read-only), but never move/resize. */}
+          {canEdit && selectedObject && <SelectionOverlay object={selectedObject} gardenId={garden.id} svgRef={svgRef} />}
+          {canEdit && selectedPlop && selectedPlopObject && (
             <PlopOverlay plop={selectedPlop} object={selectedPlopObject} gardenId={garden.id} svgRef={svgRef} />
           )}
 
           {/* Placement capture: a transparent sheet over the focused object while a
               plant is armed, so taps drop plops instead of selecting the object. */}
-          {focusedObject && armedPlant && focusedObject.plantable && (
+          {canEdit && focusedObject && armedPlant && focusedObject.plantable && (
             <g transform={objectTransform(focusedObject)}>
               <rect
                 x={-halfFW}
diff --git a/web/src/editor/Inspector.tsx b/web/src/editor/Inspector.tsx
index 250a0b5..610ee9f 100644
--- a/web/src/editor/Inspector.tsx
+++ b/web/src/editor/Inspector.tsx
@@ -27,11 +27,13 @@ export function Inspector({
   gardenId,
   unit,
   onFocus,
+  readOnly = false,
 }: {
   object: EditorObject
   gardenId: number
   unit: UnitPref
   onFocus?: () => void
+  readOnly?: boolean
 }) {
   const update = useUpdateObject(gardenId)
   const del = useDeleteObject(gardenId)
@@ -96,19 +98,26 @@ export function Inspector({
         </button>
       </div>
 
-      {object.plantable && onFocus && (
+      {readOnly && (
+        <p className="rounded-md bg-border/40 px-2 py-1 text-xs text-muted">View only — you can't edit this garden.</p>
+      )}
+
+      {!readOnly && object.plantable && onFocus && (
         <Button onClick={onFocus} className="w-full">
           🌱 Plant here
         </Button>
       )}
 
-      <TextField
-        label="Name"
-        name="name"
-        value={name}
-        onChange={(e) => setName(e.target.value)}
-        onBlur={() => name !== object.name && patch({ name })}
-      />
+      {/* A disabled fieldset makes every control below read-only for viewers in
+          one shot (no per-input disabled). */}
+      <fieldset disabled={readOnly} className="flex min-w-0 flex-col gap-3 border-0 p-0">
+        <TextField
+          label="Name"
+          name="name"
+          value={name}
+          onChange={(e) => setName(e.target.value)}
+          onBlur={() => name !== object.name && patch({ name })}
+        />
 
       <div className="grid grid-cols-2 gap-2">
         <TextField
@@ -207,37 +216,39 @@ export function Inspector({
         Plantable
       </label>
 
-      <TextArea
-        label="Notes"
-        name="notes"
-        rows={2}
-        value={notes}
-        onChange={(e) => setNotes(e.target.value)}
-        onBlur={() => notes !== object.notes && patch({ notes })}
-      />
+        <TextArea
+          label="Notes"
+          name="notes"
+          rows={2}
+          value={notes}
+          onChange={(e) => setNotes(e.target.value)}
+          onBlur={() => notes !== object.notes && patch({ notes })}
+        />
+      </fieldset>
 
-      {confirmingDelete ? (
-        <div className="flex items-center gap-2">
-          <Button
-            variant="danger"
-            className="flex-1"
-            disabled={del.isPending}
-            onClick={() => {
-              select(null)
-              del.mutate(object.id)
-            }}
-          >
-            Confirm delete
+      {!readOnly &&
+        (confirmingDelete ? (
+          <div className="flex items-center gap-2">
+            <Button
+              variant="danger"
+              className="flex-1"
+              disabled={del.isPending}
+              onClick={() => {
+                select(null)
+                del.mutate(object.id)
+              }}
+            >
+              Confirm delete
+            </Button>
+            <Button variant="ghost" onClick={() => setConfirmingDelete(false)}>
+              Cancel
+            </Button>
+          </div>
+        ) : (
+          <Button variant="ghost" className="text-red-600 dark:text-red-400" onClick={() => setConfirmingDelete(true)}>
+            Delete object
           </Button>
-          <Button variant="ghost" onClick={() => setConfirmingDelete(false)}>
-            Cancel
-          </Button>
-        </div>
-      ) : (
-        <Button variant="ghost" className="text-red-600 dark:text-red-400" onClick={() => setConfirmingDelete(true)}>
-          Delete object
-        </Button>
-      )}
+        ))}
     </div>
   )
 }
diff --git a/web/src/editor/PlopInspector.tsx b/web/src/editor/PlopInspector.tsx
index c7ad5b9..dc38de4 100644
--- a/web/src/editor/PlopInspector.tsx
+++ b/web/src/editor/PlopInspector.tsx
@@ -25,6 +25,7 @@ export function PlopInspector({
   unit,
   onChangePlant,
   onClose,
+  readOnly = false,
 }: {
   plop: EditorPlanting
   plant?: Plant
@@ -32,6 +33,7 @@ export function PlopInspector({
   unit: UnitPref
   onChangePlant: () => void
   onClose: () => void
+  readOnly?: boolean
 }) {
   const update = useUpdatePlanting(gardenId)
   const remove = useRemovePlanting(gardenId)
@@ -104,6 +106,10 @@ export function PlopInspector({
         </button>
       </div>
 
+      {readOnly && (
+        <p className="rounded-md bg-border/40 px-2 py-1 text-xs text-muted">View only — you can't edit this garden.</p>
+      )}
+
       <div className="flex items-center gap-2 rounded-lg border border-border p-2">
         {plant ? (
           <PlantIcon color={plant.color} icon={plant.icon} className="h-9 w-9 rounded-md text-xl" />
@@ -111,11 +117,14 @@ export function PlopInspector({
           <span className="grid h-9 w-9 place-items-center rounded-md bg-border/50 text-muted">?</span>
         )}
         <span className="min-w-0 flex-1 truncate text-sm font-medium text-fg">{plant?.name ?? 'Unknown plant'}</span>
-        <Button variant="ghost" className="px-2 py-1 text-xs" onClick={onChangePlant}>
-          Change
-        </Button>
+        {!readOnly && (
+          <Button variant="ghost" className="px-2 py-1 text-xs" onClick={onChangePlant}>
+            Change
+          </Button>
+        )}
       </div>
 
+      <fieldset disabled={readOnly} className="flex min-w-0 flex-col gap-3 border-0 p-0">
       <div className="grid grid-cols-2 gap-2">
         <TextField
           label={`Radius (${u})`}
@@ -151,26 +160,29 @@ export function PlopInspector({
         onBlur={() => label !== (p.label ?? '') && patch({ label: label.trim() || null })}
       />
 
-      <TextField
-        label="Planted"
-        name="planted"
-        type="date"
-        value={planted}
-        onChange={(e) => setPlanted(e.target.value)}
-        onBlur={commitPlanted}
-      />
+        <TextField
+          label="Planted"
+          name="planted"
+          type="date"
+          value={planted}
+          onChange={(e) => setPlanted(e.target.value)}
+          onBlur={commitPlanted}
+        />
+      </fieldset>
 
-      <Button
-        variant="ghost"
-        className="text-red-600 dark:text-red-400"
-        disabled={remove.isPending}
-        onClick={() => {
-          onClose()
-          remove.mutate({ id: plop.id, version: plop.version })
-        }}
-      >
-        Remove plant
-      </Button>
+      {!readOnly && (
+        <Button
+          variant="ghost"
+          className="text-red-600 dark:text-red-400"
+          disabled={remove.isPending}
+          onClick={() => {
+            onClose()
+            remove.mutate({ id: plop.id, version: plop.version })
+          }}
+        >
+          Remove plant
+        </Button>
+      )}
     </div>
   )
 }
diff --git a/web/src/lib/gardens.ts b/web/src/lib/gardens.ts
index a95410b..0f943e9 100644
--- a/web/src/lib/gardens.ts
+++ b/web/src/lib/gardens.ts
@@ -8,6 +8,9 @@ import type { UnitPref } from './units'
 
 const unitPrefSchema = z.enum(['metric', 'imperial'])
 
+export const gardenRoleSchema = z.enum(['owner', 'editor', 'viewer'])
+export type GardenRole = z.infer<typeof gardenRoleSchema>
+
 export const gardenSchema = z.object({
   id: z.number(),
   ownerId: z.number(),
@@ -19,9 +22,22 @@ export const gardenSchema = z.object({
   version: z.number(),
   createdAt: z.string(),
   updatedAt: z.string(),
+  // The actor's effective role on this garden (owner/editor/viewer). Present on
+  // every accessible response; optional defensively.
+  myRole: gardenRoleSchema.optional(),
 })
 export type Garden = z.infer<typeof gardenSchema>
 
+/** Whether a role may edit garden contents (objects/plops). Unknown → false. */
+export function canEditRole(role?: GardenRole): boolean {
+  return role === 'owner' || role === 'editor'
+}
+
+/** Whether a role owns the garden (may edit metadata, manage shares, delete). */
+export function isOwnerRole(role?: GardenRole): boolean {
+  return role === 'owner'
+}
+
 const gardensKey = ['gardens'] as const
 
 export const gardensQueryOptions = queryOptions({
diff --git a/web/src/lib/shares.ts b/web/src/lib/shares.ts
new file mode 100644
index 0000000..dee24c6
--- /dev/null
+++ b/web/src/lib/shares.ts
@@ -0,0 +1,69 @@
+// Garden sharing data layer: zod shapes for /gardens/:id/shares plus the
+// react-query hooks the share dialog and "leave garden" action use.
+
+import { queryOptions, useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+import { z } from 'zod'
+import { api } from './api'
+
+export const shareRoleSchema = z.enum(['viewer', 'editor'])
+export type ShareRole = z.infer<typeof shareRoleSchema>
+
+export const shareSchema = z.object({
+  id: z.number(),
+  gardenId: z.number(),
+  userId: z.number(),
+  role: shareRoleSchema,
+  createdBy: z.number(),
+  version: z.number(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  email: z.string(),
+  displayName: z.string(),
+})
+export type Share = z.infer<typeof shareSchema>
+
+const sharesKey = (gardenId: number) => ['shares', gardenId] as const
+
+export function sharesQueryOptions(gardenId: number) {
+  return queryOptions({
+    queryKey: sharesKey(gardenId),
+    queryFn: async (): Promise<Share[]> => z.array(shareSchema).parse(await api.get(`/gardens/${gardenId}/shares`)),
+  })
+}
+
+/** The shares on a garden (owner-only endpoint; pass enabled=false to skip). */
+export function useShares(gardenId: number, enabled = true) {
+  return useQuery({ ...sharesQueryOptions(gardenId), enabled })
+}
+
+export function useAddShare(gardenId: number) {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: async (input: { email: string; role: ShareRole }): Promise<Share> =>
+      shareSchema.parse(await api.post(`/gardens/${gardenId}/shares`, input)),
+    onSuccess: () => qc.invalidateQueries({ queryKey: sharesKey(gardenId) }),
+  })
+}
+
+export function useUpdateShareRole(gardenId: number) {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: async ({ userId, role }: { userId: number; role: ShareRole }): Promise<Share> =>
+      shareSchema.parse(await api.patch(`/gardens/${gardenId}/shares/${userId}`, { role })),
+    onSuccess: () => qc.invalidateQueries({ queryKey: sharesKey(gardenId) }),
+  })
+}
+
+/** Remove a share. Used both by the owner (revoke) and by a recipient leaving a
+ *  garden (their own userId). Refreshes the garden list too, since a leave
+ *  changes what the current user can see. */
+export function useRemoveShare(gardenId: number) {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: (userId: number) => api.delete(`/gardens/${gardenId}/shares/${userId}`),
+    onSuccess: () => {
+      qc.invalidateQueries({ queryKey: sharesKey(gardenId) })
+      qc.invalidateQueries({ queryKey: ['gardens'] })
+    },
+  })
+}
diff --git a/web/src/pages/GardenEditorPage.tsx b/web/src/pages/GardenEditorPage.tsx
index cf5b18d..e1f2110 100644
--- a/web/src/pages/GardenEditorPage.tsx
+++ b/web/src/pages/GardenEditorPage.tsx
@@ -10,6 +10,8 @@ import { Palette } from '@/editor/Palette'
 import { kindDef } from '@/editor/kinds'
 import { useEditorStore } from '@/editor/store'
 import type { EditorGarden } from '@/editor/types'
+import { ShareGardenModal } from '@/components/gardens/ShareGardenModal'
+import { canEditRole, isOwnerRole } from '@/lib/gardens'
 import { toEditorObject, useGardenFull, useUpdatePlanting } from '@/lib/objects'
 import { toEditorPlanting } from '@/lib/plantings'
 
@@ -39,6 +41,7 @@ export function GardenEditorPage() {
   // Which plant-picker flow is open: 'place' arms a plant for repeat placement;
   // 'change' swaps the selected plop's plant.
   const [picker, setPicker] = useState<'place' | 'change' | null>(null)
+  const [sharing, setSharing] = useState(false)
 
   const serverObjects = full.data?.objects
   const objects = useMemo(() => serverObjects?.map(toEditorObject) ?? [], [serverObjects])
@@ -120,6 +123,9 @@ export function GardenEditorPage() {
     heightCm: g.heightCm,
     unitPref: g.unitPref,
   }
+  // Role-driven gating from the server's my_role — never guessed client-side.
+  const canEdit = canEditRole(g.myRole)
+  const isOwner = isOwnerRole(g.myRole)
 
   const selectedObject = objects.find((o) => o.id === selectedId) ?? null
   const focusedObject = focusedObjectId != null ? objects.find((o) => o.id === focusedObjectId) ?? null : null
@@ -143,7 +149,15 @@ export function GardenEditorPage() {
         <h1 className="mb-2 truncate text-lg font-semibold tracking-tight" title={garden.name}>
           {garden.name}
         </h1>
-        {focusedObjectId == null && <Palette />}
+        {isOwner && (
+          <Button variant="ghost" className="mb-2 w-full text-sm" onClick={() => setSharing(true)}>
+            Share
+          </Button>
+        )}
+        {!canEdit && (
+          <p className="mb-2 rounded-md bg-border/40 px-2 py-1 text-xs text-muted">👁 View only</p>
+        )}
+        {focusedObjectId == null && canEdit && <Palette />}
       </div>
 
       <div className="relative min-h-0 flex-1">
@@ -155,20 +169,21 @@ export function GardenEditorPage() {
             <span className="max-w-[8rem] truncate text-muted">
               {focusedObject.name || kindDef(focusedObject.kind)?.label || 'Object'}
             </span>
-            {!focusedObject.plantable ? (
-              <span className="text-xs text-muted">Not plantable</span>
-            ) : armedPlant ? (
-              <Button variant="ghost" className="px-2 py-1 text-xs" onClick={() => setArmedPlant(null)}>
-                Placing {armedPlant.icon} — Done
-              </Button>
-            ) : (
-              <Button className="px-2 py-1 text-xs" onClick={() => setPicker('place')}>
-                + Add plant
-              </Button>
-            )}
+            {canEdit &&
+              (!focusedObject.plantable ? (
+                <span className="text-xs text-muted">Not plantable</span>
+              ) : armedPlant ? (
+                <Button variant="ghost" className="px-2 py-1 text-xs" onClick={() => setArmedPlant(null)}>
+                  Placing {armedPlant.icon} — Done
+                </Button>
+              ) : (
+                <Button className="px-2 py-1 text-xs" onClick={() => setPicker('place')}>
+                  + Add plant
+                </Button>
+              ))}
           </div>
         )}
-        <GardenCanvas garden={garden} objects={objects} plantings={plantings} plantsById={plantsById} />
+        <GardenCanvas garden={garden} objects={objects} plantings={plantings} plantsById={plantsById} canEdit={canEdit} />
       </div>
 
       {(selectedObject || selectedPlop) && (
@@ -179,6 +194,7 @@ export function GardenEditorPage() {
               object={selectedObject}
               gardenId={gid}
               unit={garden.unitPref}
+              readOnly={!canEdit}
               onFocus={() => {
                 setFocusedObject(selectedObject.id)
                 select(null)
@@ -192,6 +208,7 @@ export function GardenEditorPage() {
               plant={plantsById.get(selectedPlop.plantId)}
               gardenId={gid}
               unit={garden.unitPref}
+              readOnly={!canEdit}
               onChangePlant={() => setPicker('change')}
               onClose={() => selectPlanting(null)}
             />
@@ -206,6 +223,8 @@ export function GardenEditorPage() {
           onSelect={(p) => onPickPlant(p.id)}
         />
       )}
+
+      {sharing && <ShareGardenModal garden={g} onClose={() => setSharing(false)} />}
     </div>
   )
 }
diff --git a/web/src/pages/GardensPage.tsx b/web/src/pages/GardensPage.tsx
index 847d9ec..ed3b1df 100644
--- a/web/src/pages/GardensPage.tsx
+++ b/web/src/pages/GardensPage.tsx
@@ -4,10 +4,18 @@ import { Button } from '@/components/ui/Button'
 import { DeleteGardenModal } from '@/components/gardens/DeleteGardenModal'
 import { GardenCard } from '@/components/gardens/GardenCard'
 import { GardenFormModal } from '@/components/gardens/GardenFormModal'
+import { LeaveGardenModal } from '@/components/gardens/LeaveGardenModal'
+import { ShareGardenModal } from '@/components/gardens/ShareGardenModal'
 import { useGardens, type Garden } from '@/lib/gardens'
 
-// Which modal is open, if any. `edit`/`delete` carry the target garden.
-type Dialog = { kind: 'create' } | { kind: 'edit'; garden: Garden } | { kind: 'delete'; garden: Garden } | null
+// Which modal is open, if any. edit/delete/share/leave carry the target garden.
+type Dialog =
+  | { kind: 'create' }
+  | { kind: 'edit'; garden: Garden }
+  | { kind: 'delete'; garden: Garden }
+  | { kind: 'share'; garden: Garden }
+  | { kind: 'leave'; garden: Garden }
+  | null
 
 export function GardensPage() {
   const gardens = useGardens()
@@ -42,8 +50,10 @@ export function GardensPage() {
               <GardenCard
                 key={g.id}
                 garden={g}
+                onShare={() => setDialog({ kind: 'share', garden: g })}
                 onEdit={() => setDialog({ kind: 'edit', garden: g })}
                 onDelete={() => setDialog({ kind: 'delete', garden: g })}
+                onLeave={() => setDialog({ kind: 'leave', garden: g })}
               />
             ))}
           </div>
@@ -53,6 +63,8 @@ export function GardensPage() {
       {dialog?.kind === 'create' && <GardenFormModal onClose={close} />}
       {dialog?.kind === 'edit' && <GardenFormModal garden={dialog.garden} onClose={close} />}
       {dialog?.kind === 'delete' && <DeleteGardenModal garden={dialog.garden} onClose={close} />}
+      {dialog?.kind === 'share' && <ShareGardenModal garden={dialog.garden} onClose={close} />}
+      {dialog?.kind === 'leave' && <LeaveGardenModal garden={dialog.garden} onClose={close} />}
     </section>
   )
 }