use-chisel 0.1.0 → 0.1.2

package/README.md

@@ -1,16 +1,55 @@
 # use-chisel
 
+## Combined Workspace
+
+`use-chisel/workspace` exports `ChiselWorkspace`, `ChiselPreview`,
+`ChiselWorkspaceStyles`, and the `WorkspaceUser` type. Mount `ChiselPreview`
+in your layout and render `ChiselWorkspace` in an authenticated `/chisel` route.
+Pass `user`, `validateSession: () => Promise<boolean>`, and
+`signOut: () => Promise<void>` through a client component. Authentication and
+route handling belong to the host app; see the repository demo for Supabase Auth
+with Google.
+
+Edit, Comment, and View share one toolbar. Threads expand from element pins;
+history appears in the sidebar.
+Use **E** for Edit, **C** for Comment, and **V** for View. **Shift+C** toggles
+all comment pins, threads, and the comments sidebar. Shortcuts are ignored
+while typing in form fields or editable content. Comments are browser-local by
+default. Pass a `CommentStore` with `list()` and `mutate(change)` to share them;
+mutations create a comment, edit its proposal, append one reply, or resolve a
+thread. Implement optional `delete(id)` to expose deletion for authors and site
+owners; enforce these permissions in the backend. Keep the client-generated
+comment/reply UUID when retrying a failed mutation so the adapter can make writes
+idempotent. The demo uses authenticated Supabase endpoints with server-derived
+authors; see `apps/demo/lib/comments.ts` and `supabase/` for its adapter, migrations,
+and reviewer access policies.
+`canManageComments` exposes management controls for other reviewers’ threads; optional
+`getReviewLink(rotate?)` enables sharing a client review link.
+The host must enforce
+these permissions in its backend as the demo does. The tweak editor is development-only. The standalone API below remains
+supported.
+
+To close reviews when a site goes live, disable the preview integration and
+return 404 from the workspace route on the server. The demo host implements this
+with `CHISEL_ENABLED=0`; production defaults off and staging explicitly sets `1`.
+This is host configuration, not a client-side security toggle in the npm package.
+
 Dev-only visual editing layer for Next.js apps.
 
+Supports Next.js 14 through 16 with React 18 or 19, including both App Router and Pages Router projects.
+
 ## Install
 
 ```bash
 npm install use-chisel
 ```
 
+Run `npx chisel` to open the hosted Chisel sign-in page. Connecting your project
+to the hosted workspace is not available yet.
+
 ## Use
 
-Mount `Chisel` in your app layout during development:
+Mount `Chisel` in your app layout:
 
 ```tsx
 import { Chisel } from "use-chisel"
@@ -20,13 +59,19 @@ export default function RootLayout({ children }: { children: React.ReactNode })
     <html lang="en">
       <body>
         {children}
-        {process.env.NODE_ENV === "development" ? <Chisel /> : null}
+        <Chisel />
       </body>
     </html>
   )
 }
 ```
 
+Open any route with `?editor` to show the editor:
+
+```txt
+http://localhost:3000?editor
+```
+
 Add `EditableRegion` when you want copied prompts to include stable source hints:
 
 ```tsx
@@ -35,8 +80,28 @@ import { EditableRegion } from "use-chisel"
 <EditableRegion id="homepage.hero.title">Launch faster</EditableRegion>
 ```
 
+Chisel persists route versions in the browser. Local image files are previewed only for the current session; after a reload, re-select the file when prompted. Chisel inspects same-document light DOM. Cross-origin iframes and closed shadow roots are not supported.
+
 ## Publish
 
 ```bash
 npm publish --workspace use-chisel --access public
 ```
+
+A realtime comment adapter can implement optional `CommentStore.subscribe(onChange)`;
+return an unsubscribe function. The workspace refreshes after notifications instead
+of its fallback polling interval. Optional `collaboration` props provide online
+reviewers, page presence, unread thread IDs, and read tracking. A realtime adapter should refresh on reconnect/focus and recover
+when its connection is unavailable. Only acknowledge message activity the reviewer
+has actually seen. The demo's Supabase integration uses these interfaces without
+adding a database SDK dependency to this package.
+
+Optional `commentUI` renderers can replace the thread and composer while retaining
+Chisel's workspace behavior. The composer receives
+`renderContent(editor, hasAttachments?, uploading?)` to keep settings, Cancel,
+dictation, and explicit submit in the same form. Custom rich text can be passed as
+optional mutation `body`, with validated upload IDs in `attachmentTokens`. Adapters
+must validate both before storing them and bind uploads to the authenticated user
+and site. Keep the editor and attachment draft when `onSubmit` or `onReply` returns
+`false`; release it only after a successful save. Slate and Supabase remain demo
+dependencies. The built-in local UI remains available without either dependency.

package/bin/chisel.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+
+const url = "https://chisel-review.vercel.app/chisel/start";
+console.log(`Open ${url} to sign in to Chisel.`);
+const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "rundll32" : "xdg-open";
+const args = process.platform === "win32" ? ["url.dll,FileProtocolHandler", url] : [url];
+const browser = spawn(command, args, { detached: true, stdio: "ignore" });
+browser.on("error", () => console.error("Could not open a browser. Open the link above instead."));
+browser.unref();

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export type ChiselProps = {
     enabled?: boolean;
     position?: "left" | "right";
     projectName?: string;
+    embedded?: boolean;
 };
 export type DOMRectJSON = {
     x: number;
@@ -34,11 +35,16 @@ export type EditIntent = {
         before: string | number | null;
         after: string | number;
     }>;
+    asset?: {
+        fileName: string;
+        mimeType: string;
+        size: number;
+    };
 };
 type EditableRegionProps = React.HTMLAttributes<HTMLSpanElement> & {
     id: string;
-    as?: keyof JSX.IntrinsicElements;
+    as?: keyof React.JSX.IntrinsicElements;
 };
 export declare function EditableRegion({ id, as, children, ...props }: EditableRegionProps): React.JSX.Element;
-export declare function Chisel({ enabled, position, projectName }: ChiselProps): React.JSX.Element | null;
+export declare function Chisel({ enabled, position, projectName, embedded }: ChiselProps): React.JSX.Element | null;
 export {};