Design Workspace: local-first projects and dedicated Design mode

.gitignore

@@ -42,7 +42,7 @@ Thumbs.db
 tmp/*
 
 # Local agent troubleshooting notes
-.papercuts/
+**/.papercuts/
 
 # Local git worktrees
 .worktrees/

AGENTS.md

@@ -26,7 +26,7 @@ OpenRouter benchmark insights are also manual-only. The live app may contact onl
 
 ## Papercuts
 
-For complex workflows, record concise implementation friction in `.papercuts/troubleshooting.md` as it occurs.
+Papercut notes are machine-local scratch and are intentionally ignored by Git. For complex workflows, record concise implementation friction in `.papercuts/troubleshooting.md` as it occurs, but do not commit the folder or its contents.
 
 ## Tests
 

README.md

@@ -21,6 +21,7 @@ I don't come from a coding background. I'd been bouncing between the coding agen
 ## Features
 
 - **Aiden Assistant** - press `⌘⌥A` to open a private assistant dock inside the main window. It follows the selected chat model, keeps its own local history and drafts, supports Stop, and can explain the app without receiving workspace tools or a hidden copy of the workspace.
+- **Design Workspace** - open Design from the persistent sidebar and work on a durable React Flow-powered canvas of live, network-free HTML artboards and image references. Projects restore their exact canvas, history, comments, and source connection; Preview, Code, export, design-system context, reviewed multi-file actions, hash-safe Undo, and recoverable workspace handoff are built in. See the [shipped MVP](docs/plans/completed/design-workspace-plan.md) and [completed durable-project follow-on](docs/plans/completed/design-workspace-claude-alignment-plan.md).
 - **Command palette and shortcuts** - `⌘K` searches commands, chats, models, providers, Settings, and appearance actions. One typed command system also powers native menus, visible shortcut labels, transactional global hotkeys, and the searchable Keyboard Shortcuts editor.
 - **Commands and explicit skills** - type `/` at the start of the composer to search Aiden app commands, or `$` to search the active workspace's available skills. Commands reuse canonical app workflows; an explicitly selected skill is revalidated for the active workspace, applies to one accepted message, and persists only safe display provenance.
 - **Native Subagents** - a foreground chat can delegate up to four fresh `scout`, `planner`, or `reviewer` tasks. Children are read/search-only, inherit the approved workspace and model, stop with the parent, and appear as live chips plus an inspectable **Subagents** view in Environment.
@@ -37,7 +38,7 @@ I don't come from a coding background. I'd been bouncing between the coding agen
 The roadmap is maintained in [the plan index](docs/plans/README.md). These bullets name only the unfinished parts of partially shipped work or features with no runtime implementation yet; they are directions, not release promises:
 
 - **Assistant tools and proactive nudges** - the private dock, shortcut, and Settings foundation ship today. The remaining work is approval-gated settings/status tools plus opt-in, rate-limited suggestions about useful app and workspace maintenance. See the [Aiden Assistant plan](docs/plans/aiden-assistant-plan.md).
-- **Designer Mode** - no Designer Mode runtime exists yet. The proposed flow selects UI in a local Vite app, requests a bounded change, requires approval, and reviews the exact action diff; Phase 0 remains a go/no-go validation gate. See the [Designer Mode plan](docs/plans/designer-mode-plan.md).
+- **Durable Design Projects and handoff** - named local projects persist the full canvas and expose Preview, Code, History, deterministic standalone/ZIP export, managed-worktree-first **Continue in workspace**, local design-system context, comments, bounded direct manipulation, and reviewed source changes. See the [completed Design Workspace follow-on plan](docs/plans/completed/design-workspace-claude-alignment-plan.md).
 - **Static-catalog overlays and provider completion** - Pi built-in discovery, encrypted credentials, provider-owned authentication, native streaming, stored dynamic catalogs, manual refresh, and voice credential lookup already ship. Remaining work includes remote overlays for otherwise-static hosted catalogs, Pi-native custom-endpoint composition, historical message provenance, scalable large-catalog recovery UX, and rollout cleanup. See the [Dynamic Model Catalog](docs/plans/dynamic-model-catalog-plan.md) and [Pi Provider Integration](docs/plans/pi-provider-integration-plan.md) plans.
 - **Truthful generation progress notes** - no progress-note runtime exists yet. The plan would show one temporary acknowledgement after an otherwise-silent start, using an explicitly selected on-device or verified hosted route without exposing hidden reasoning. See the [Generation Progress Notes plan](docs/plans/generation-progress-notes-plan.md).
 - **Long-session context and run control** - model-aware deterministic compaction already ships. Remaining work includes visible compaction activity, reconstructable structured checkpoints, durable-versus-working memory separation, queued follow-up messages, and safe mid-run redirects. See the [Compaction](docs/plans/compaction-plan.md) and [Taracodlab Learnings](docs/plans/taracodlab-learnings-plan.md) plans.

THIRD_PARTY_NOTICES.md

@@ -36,6 +36,22 @@ Copyright (c) 2013-2026 Khan Academy and other contributors
 
 MIT License. See https://github.com/KaTeX/KaTeX/blob/main/LICENSE.txt
 
+## React Flow
+
+`@xyflow/react` powers the spatial Design Workspace canvas.
+
+Copyright (c) 2019-2025 webkid GmbH
+
+MIT License. See https://github.com/xyflow/xyflow/blob/main/LICENSE
+
+## React Grab
+
+A minimized bundle of `react-grab/primitives` is vendored into `resources/generative-ui` for Design-only element hit testing inside sandboxed preview guests. Aiden does not initialize React Grab's full overlay or telemetry path.
+
+Copyright (c) 2025 Aiden Bai
+
+MIT License. See https://github.com/aidenybai/react-grab/blob/main/LICENSE
+
 ## rpiv extensions
 
 Aiden's native extensions adapt interaction and state-management ideas from

docs/architecture/design-comments-direct-edits.md

@@ -0,0 +1,86 @@
+# Design comments and bounded direct edits
+
+Status: Implemented. Comments, direct-edit IPC, pointer/keyboard controls, durable connected review,
+prototype revision creation, and exact immutable undo are wired.
+
+## Authority boundary
+
+Comments and direct-manipulation gestures are context. They never grant repository, command,
+network, Git, preview-session, or artifact-write authority.
+
+A comment target is durable only when all of these identities are present:
+
+- Design Project ID;
+- artboard lineage ID;
+- immutable revision media ID;
+- an exact, single-match selector identity; and
+- either the generated artifact content hash or a relative, source-version/range/preimage-hash
+  connected-source identity.
+
+An ephemeral React Grab selection or preview capability is insufficient and is never persisted.
+When the current immutable revision or full source binding changes, the store marks the older
+comment stale. Stale comments remain visible and can be resolved or reopened, but are never
+silently retargeted.
+
+The comment store is main-owned, atomic, schema- and byte-bounded, and written with mode `0600`.
+All writes use both database revision CAS and, for existing comments, comment revision CAS.
+Corrupt or unsupported on-disk data makes the store unavailable rather than allowing a later
+write to replace it.
+
+## Literal edit matrix
+
+The direct-edit core accepts only:
+
+- margin, padding, and gap spacing literals;
+- width and height literals;
+- enumerated alignment values;
+- semantic CSS custom-property token names for color roles;
+- border-radius literals; and
+- bounded static plain text.
+
+CSS expressions, URLs, raw colors, arbitrary properties, negative values, markup-like text,
+localized or dynamic text, rich text, computed classes, ambiguous selector/component matches,
+and repeated literal-definition matches fail closed. Proof facts must report exactly one selector,
+component, and literal definition match.
+
+Within one accepted gesture envelope, the proposal and undo identities are deterministic. That
+gives the integration coordinator one idempotency key and one future undo record. A renderer IPC
+retry is a new attended gesture with a newly minted gesture ID; it is not deduplicated against a
+previous ambiguous request.
+
+## Origin-specific output
+
+Prototype edits produce a `prototype-revision-request` pinned to the base media ID and artifact
+hash. The request instructs an artifact adapter to create a new immutable revision; the core never
+overwrites artifact bytes.
+
+The main adapter re-reads the committed source, verifies its SHA-256 identity, proves one exact
+`data-aiden-id` target and one literal inline definition, and derives a deterministic new media ID
+from the proposal. It stages the new bytes, CAS-appends the lineage in the Design Project, appends
+the chat artifact idempotently, and only then commits the staged bytes. A pre-CAS failure discards
+only the exact pending row. A post-CAS interruption deliberately leaves the pending row for the
+existing startup recovery path, so retries and restarts converge on one immutable revision.
+
+Connected-app edits produce a `designer-action-request` carrying the relative path, full source
+version, exact range, preimage, and independently verified preimage hash. The core never writes
+source. An integration adapter must turn that semantic literal edit into one exact replacement,
+then submit it through the existing Designer Action review/apply/undo transaction. Full permission
+must not bypass that review.
+
+The connected adapter resolves the live source-selection capability again, compares every path,
+version, range, preimage, hash, and selector fact with the proposal, and parses the canonical TSX.
+Only a single literal inline JSX style property or a single plain JSX text node is rewritten. The
+caller must also provide a trusted source-graph proof that the enclosing component has one use;
+missing or ambiguous graph evidence fails closed. The result is submitted to
+`SourceDesignerActionService.propose`, so apply and undo retain the same review transaction as
+every other Designer Action.
+
+## Intentional limitations
+
+The
+prototype adapter intentionally supports only literal inline HTML style declarations and plain
+text nodes. The connected adapter intentionally supports only literal inline JSX style objects and
+plain JSX text nodes. Stylesheets, classes, spreads, expressions, component indirection, localized
+text, rich children, ambiguous selectors, and repeated definitions fail closed instead of being
+guessed. Color changes additionally require the main caller to resolve the token from the current
+trusted design-system snapshot; renderer-reported token names are never sufficient authority.

docs/architecture/design-handoff.md

@@ -0,0 +1,90 @@
+# Design handoff architecture
+
+Status: Implemented. Coordinator, production effects, startup recovery, IPC, chat/model context,
+renderer confirmation, cancellation, recovery, and project linkage are connected.
+
+## Boundary
+
+**Continue in workspace** graduates one immutable Prototype revision into an ordinary workspace task. It does not turn the Design Project into a source-writing authority. The handoff coordinator has no filesystem, Git, command, model, provider, staging, commit, push, pull-request, deployment, or application-source write API.
+
+The only content crossing the boundary is a parsed `DesignHandoffPacketV1`:
+
+- Design Project ID and compare-and-swap revision;
+- immutable source bundle, lineage, and revision IDs plus its SHA-256 and byte size;
+- content-addressed reference asset IDs;
+- bounded, normalized design-decision summaries; and
+- bounded desktop, tablet, and phone dimensions.
+
+The exact-key parser rejects unknown fields. In particular, there is no field for a prompt, transcript, internal project JSON, provider/model credentials, absolute path, arbitrary source bytes, tool authority, or source-write instruction. Decision text is conservatively rejected when it resembles a credential, absolute path, or serialized internal JSON. The installed packet is explicitly untrusted design context; subsequent implementation uses normal workspace chat permissions, file-tool approval, and Review.
+
+## Target confirmation
+
+The durable journal is path-free. Both target variants contain a renderer-safe four-label preview (`workspaceId`, workspace label, repository label, and branch label) and a SHA-256 digest of that exact preview. A production `verifyTarget` port must re-resolve authoritative main-process state immediately before any effect and return the same parsed target.
+
+The default target is an Aiden-managed worktree. The confirmation records committed `HEAD`, whether the source checkout was dirty, and the exact disclosure acknowledgment when dirty: uncommitted source-checkout changes are not included. `prepareWorkspace` must use the existing managed-worktree application service, create from that committed `HEAD`, and return matching `createdFromHead` evidence.
+
+An existing authorized workspace is accepted only with the exact strong-warning acknowledgment and target-preview digest. Main revalidates the workspace ID and the preview before use. This path reuses the existing workspace; it does not create or remove a worktree.
+
+## Journal and publication boundary
+
+`DesignHandoffJournalStore` owns `design-handoffs.json` under Electron `userData`. It uses `DataStore` atomic replacement, mode `0600`, a 2 MiB read ceiling, strict versioned parsing, a maximum of 128 records, compare-and-swap revisions, external reload before writes, and fail-closed corrupt/unsafe-file handling. It retains active and recoverable records; the oldest terminal record may be evicted only when the bound is reached.
+
+The coordinator advances these durable stages:
+
+```text
+prepared
+  -> workspace-ready
+  -> chat-ready
+  -> context-ready
+  -> published
+```
+
+Every effect receives the stable operation ID and must be idempotent by that ID. A crash after an effect but before its journal checkpoint therefore repeats discovery of the same worktree, chat, context installation, or project link rather than creating another one. Illegal stage skips, identity replacement, cancellation clearing, and stale revisions are rejected.
+
+Project-link publication is the visible commit boundary. A publication call with an unknown outcome is reconciled with `inspectPublication(operationId)` before retry or rollback. The published linkage records the project, workspace, chat, task, and branch display identity. Publication does not grant the Prototype future workspace authority.
+
+## Cancellation and recovery
+
+Before publication, cancellation is journaled and rollback is attempted in reverse order:
+
+1. remove the installed handoff context;
+2. remove the new chat/task; and
+3. roll back the new managed workspace.
+
+Rollback ports also discover effects solely by operation ID. This covers cancellation or a crash between an external effect and its journal checkpoint. Each rollback returns a proof result. If any result is unknown or false, the coordinator stops destructive rollback, preserves the remaining workspace, and records a renderer-safe `recoverable` reason. It never reports the repository unchanged without proof.
+
+If publication is observed—or cancellation arrives after the published checkpoint—the coordinator preserves the linked workspace and records `recoverable`. Startup can call `resumeRecoverable()` to resume nonterminal records idempotently. Terminal `published` and `rolled-back` entries are not replayed.
+
+## Production port mapping
+
+The core deliberately defines injected ports. Production integration should map them as follows:
+
+- `verifyTarget`: authoritative config/workspace/Git-state resolution, including dirty state and committed HEAD;
+- `prepareWorkspace`: existing `workspaceWorktreeApplicationService.create` for managed targets, or authoritative lookup for the explicitly acknowledged existing workspace;
+- `createChat`: existing chat application service, tagged durably by handoff operation ID;
+- `installUntrustedContext`: a bounded main-owned task-context record, not a hidden user prompt or source write;
+- `publishProjectLink`: one compare-and-swap Design Project update that makes the task linkage visible;
+- `inspectPublication`: authoritative Design Project lookup by operation ID;
+- rollback ports: existing chat/worktree cleanup services plus durable proof that the operation-owned effect is absent.
+
+The production adapters must preserve the operation ID in their own effect records so “idempotent” is a verified property, not a coordinator assumption. They must not shell out directly; Git and worktree work stays behind existing application services.
+
+## Production effect integration
+
+`DesignHandoffEffectStore` owns a second owner-only, bounded ledger, `design-handoff-effects.json`. The coordinator journal records the cross-store state machine; this effect ledger records the operation-keyed identities needed to rediscover effects after a crash. It stores only workspace/chat/task IDs, renderer-safe labels, the parsed handoff packet, and the published linkage. It does not store repository paths, source bytes, prompts, credentials, Git capabilities, or tool authority.
+
+The existing managed-worktree and chat application services do not accept a caller-owned effect ID. The production adapter therefore derives a deterministic `feature/design-handoff-<digest>` branch and a visible `Design handoff · <digest>` chat title from the operation ID. Before creating either effect it searches authoritative main-owned records for that tag. The effect ledger then binds the discovered/generated workspace and chat identities to the operation. An ambiguous discovery fails closed.
+
+Managed target inspection pairs the current Review snapshot with the cohesive committed Git `HEAD`. `verifyTarget` repeats that inspection immediately before any effect and requires the exact preview, dirty state, and commit the person confirmed. Worktree creation remains behind `workspaceWorktreeApplicationService.create`; its returned `createdFromHead` must equal the confirmation. A new managed handoff workspace is changed to `ask` permission before chat creation, so ordinary source writes and shell work retain Aiden's approval gates. An existing workspace retains its already-authorized permission and is never deleted by handoff rollback.
+
+The workspace chat is an ordinary non-Bot chat. Aiden currently has no separate durable Task entity, so the published `taskId` is the chat ID; both identities remain explicit in the linkage. The packet is installed in the main-owned effect ledger as untrusted task context, not appended as a hidden system/user prompt. `contextForChat(chatId)` adds that bounded context to the visible task and accepted model turn.
+
+Before context installation and again at publication, the production binding verifies the Design Project CAS revision, generated-artifact lineage/revision membership, committed source byte length and SHA-256, and the existence and project ownership of each content-addressed reference asset. Publication writes a separate project-indexed linkage in the effect ledger; it does not grant workspace authority back to the prototype or modify the project snapshot.
+
+`designHandoffApplicationService.initialize()` initializes the effect ledger. `reconcileAtStartup()` is an explicit startup hook that resumes every nonterminal journal independently, returning renderer-safe failures while logging private diagnostics. The service also exposes target previews, begin/cancel/resume, project links, and chat context for the main handler layer.
+
+## Current limitations
+
+Handoff creates or reuses a local workspace and an ordinary Aiden chat/task. It does not implement
+hosted collaboration, deployment, pull-request creation, or automatic source writes. Recoverable
+records remain explicit and can be resumed or cancelled from the owning project.