refactor(scratchpad): unify editor transactions and interaction state

[johnnyjoygh]

Summary by CodeRabbit

• New Features

  • Added scratchpad toolbar with instance settings, theme switcher, and navigation controls
  • Enabled canvas pan and zoom via scroll wheel interactions
  • Enhanced card drag and resize with live interaction previews

• Documentation

  • Updated API documentation references
  • Added architecture planning and design documentation

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 436d26e3-e7bc-4e1b-a6e8-adbb8dcce02a

📥 Commits

Reviewing files that changed from the base of the PR and between 5ffd0e1 and 0ac0373.

📒 Files selected for processing (18)

• content/docs/api/0-26-2/index.mdx
• docs/issues/2026-04-01-scratchpad-editor-architecture/definition.md
• docs/issues/2026-04-01-scratchpad-editor-architecture/design.md
• docs/issues/2026-04-01-scratchpad-editor-architecture/execution.md
• docs/issues/2026-04-01-scratchpad-editor-architecture/plan.md
• next-env.d.ts
• openapi/latest.yaml
• src/app/scratchpad/page.tsx
• src/components/scratch/card-item.tsx
• src/components/scratch/scratchpad-toolbar.tsx
• src/components/scratch/workspace.tsx
• src/hooks/use-scratchpad-editor.ts
• src/hooks/use-scratchpad.ts
• src/lib/scratch/editor.ts
• src/lib/scratch/interactions.ts
• src/lib/scratch/storage.ts
• src/lib/scratch/types.ts
• src/lib/scratch/viewport.ts

---

📝 Walkthrough

Walkthrough

A comprehensive refactoring of the scratchpad editor introduces a centralized state management layer with explicit viewport/camera handling, pointer interaction utilities, and viewport persistence. Components are restructured to consume editor state and viewport props, with a new toolbar component extracting page-level controls. Documentation files detail the architectural problem statement, design goals, and implementation plan.

Changes

Cohort / File(s)	Summary
Documentation content/docs/api/0-26-2/index.mdx, docs/issues/2026-04-01-scratchpad-editor-architecture/*	Minor API docs wording update and new architectural documentation (definition, design, execution, plan) for scratchpad editor refactor.
Type Definitions & Storage src/lib/scratch/types.ts, src/lib/scratch/viewport.ts, src/lib/scratch/storage.ts	New ScratchpadViewport type interface; viewport defaults, zoom parameters, and coordinate transformation utilities; storage support for persisting and retrieving viewport state.
Pointer Interaction Utilities src/lib/scratch/interactions.ts	New module defining typed pointer session and pointer interaction state management with helpers for session tracking, threshold detection, and pointer capture control.
Editor State & Logic src/lib/scratch/editor.ts, src/hooks/use-scratchpad-editor.ts	New editor state reducer with transaction-based persistence control, item/selection/viewport mutation operations, and hook encapsulating reducer initialization, hydration, persistence, and action dispatcher with attachment/file upload handling.
Hook Refactoring src/hooks/use-scratchpad.ts	Delegated item management to useScratchpadEditor(); simplified instance loading; updated save flow and selection computation to use editor's state and functions.
UI Components src/components/scratch/card-item.tsx, src/components/scratch/workspace.tsx, src/components/scratch/scratchpad-toolbar.tsx, src/app/scratchpad/page.tsx	Replaced framer-motion drag with pointer-driven interactions in card; workspace refactored to use viewport transform and handle zoom/pan via pointer events; new toolbar component for top-right controls; page simplified to composition shell wiring viewport state.
Configuration & API Schema next-env.d.ts, openapi/latest.yaml	Updated Next.js type imports path; clarified OpenAPI schema for optional tag background color.

Sequence Diagram

sequenceDiagram
    participant User
    participant Component as UI Component<br/>(Workspace/CardItem)
    participant Editor as useScratchpadEditor<br/>(State & Actions)
    participant Reducer as Editor Reducer<br/>(State Logic)
    participant Storage as Storage<br/>(localStorage)

    User->>Component: Pointer interaction<br/>(drag/zoom/select)
    Component->>Editor: Call action<br/>(setViewport/patchItem/selectItem)
    Editor->>Editor: Assign transaction ID<br/>& marshal parameters
    Editor->>Reducer: Dispatch with operations<br/>& persistence mode
    Reducer->>Reducer: Apply operations<br/>compute changes
    Reducer->>Editor: Return updated state
    Editor->>Component: Update state<br/>trigger re-render
    Component->>User: Render new viewport<br/>& item positions
    alt Persistence: immediate or debounced
        Editor->>Storage: Save items & viewport<br/>to localStorage
        Storage->>Storage: Serialize & persist
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Poem

🐰 A hop through the scratchpad we bound,
With viewports and pointers, state-managed and sound,
Where editors reign and transactions take flight,
The canvas now pans and the zoom works just right!
From drag-driven chaos to orderly grace,
We've built a fine home for this scratching-pad space. 🎨

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch scratchpad

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}