feat: keep the default Hello World buffer unsaved until the user saves

[kbuffardi]

Problem

A fresh extension session displays Hello World as an unsaved main.cpp editor tab and an empty Explorer, but the terminal reports a main.cpp file through ls, and Compile / Compile & Run treat the in-memory buffer as a compilable workspace source. These mixed signals make it appear that a file exists when it does not.

Proposed behavior

On first launch and after Start new project, retain the Hello World editor content as an unsaved buffer only. Before the user saves:

• The Explorer shows no files.
• All terminal commands except help fail with: Open a folder or save a file before using terminal commands.
• Compile and Compile & Run are disabled. They remain disabled until a workspace folder is selected and that workspace contains at least one .cpp file.

When Save is chosen from this state, it first opens a host-folder picker. After the user selects a folder, the extension asks for a filename, prefilled with main.cpp, and creates that file in the selected folder. It then binds the active buffer to that workspace file, marks it clean, refreshes Explorer and terminal state, persists the workspace session, and enables compilation when the workspace contains at least one .cpp file. Cancelling either step must preserve the untitled buffer and its existing dirty flag.

When starting a new project or opening a different folder, clear stale diagnostics, compile/run intent, terminal state, tabs, and workspace state before initializing the new state.

Existing opened-folder behavior, saving an existing workspace file, Save As, session restore prompts, and runtime write-back remain unchanged except where this issue explicitly defines the untitled state.

Unsaved document model

On fresh launch and Start new project, the editor opens an ephemeral untitled document with the Hello World template. It has no filesystem path, directory handle, workspace membership, or persisted file record.

The untitled document is represented with an explicit untitled identity (for example, kind: "untitled" and a non-path ID), not the workspace-relative main.cpp path. It has a suggested filename of main.cpp, but is not a file until Save succeeds.

The untitled document must not appear in Explorer, terminal file listings, compile overlays, diagnostics keyed to workspace paths, or session workspace metadata. The application must not write it to the host filesystem or extension/session storage.

If the prior state did not have an opened workspace folder, a new session starts in this fresh default state: no workspace, the original Hello World template, and one unsaved tab. Untitled edits are never persisted or restored.

Implementation plan

1. Model the default tab explicitly as untitled in src/ui/toolbar.js, using a non-path tab identity and suggested filename rather than main.cpp as a workspace path. Ensure tab rendering, status text, dirty tracking, diagnostics scoping, compile payload assembly, and session snapshots respect this distinction; do not render untitled tabs in Explorer.
2. Add a dedicated folder-backed Save flow for an untitled document. Open the directory picker without mutating current UI state until selection succeeds; validate and collect a filename; handle invalid names and existing-file collisions; create the selected workspace file with the current editor contents; bind the tab to its real workspace path; then mark it clean and refresh Explorer, terminal, and session state. Preserve the buffer and its existing dirty flag on cancellation.
3. Gate compilation by workspace readiness. Disable Compile and Compile & Run unless a workspace folder is open and its indexed files include at least one .cpp file. Re-evaluate that enabled state after workspace open, file create/delete/rename, and successful Save. Retain guards in the action handlers so no compiler-worker request can be posted when the controls are disabled or stale.
4. Gate the terminal while no workspace folder is open. Every terminal command except help must emit exactly Open a folder or save a file before using terminal commands. and must not read, create, list, compile, run, or expose virtual files. Once a workspace is open, preserve existing terminal semantics.
5. Establish fresh-state boundaries. When a session starts without an opened workspace folder, create only the built-in Hello World untitled document and do not persist or restore its edits. When starting a new project or opening a folder, clear tabs, workspace state, terminal state, diagnostics, compiled binaries, and compile/run intent before initializing the replacement state.
6. Add E2E coverage for the explicit untitled identity; empty Explorer; disabled Compile and Compile & Run before folder selection and until a .cpp file exists; no compiler-worker/onCompile request through stale handlers; exact terminal error for every non-help command; folder/filename save success, cancellation, validation, and collisions; post-save Explorer, terminal, and compilation behavior; fresh-state clearing; and negative assertions that untitled state never appears in extension/session storage or IndexedDB handle storage.

Acceptance criteria

• Fresh launch and Start new project show the original Hello World template in an explicit untitled tab, with no workspace-backed file; Explorer is empty.
• The default document has no filesystem path, directory handle, workspace membership, persisted file record, or extension/session storage record; its edits are never restored.
• Before a workspace folder is open, every terminal command other than help emits exactly: Open a folder or save a file before using terminal commands.
• Compile and Compile & Run are disabled unless a workspace folder is selected and contains at least one .cpp file; no disabled or stale action posts a compiler request.
• Save from the untitled state first opens a folder picker, then asks for a filename; it creates the file with the editor contents in the selected workspace folder, binds the buffer to it, and marks it clean.
• Invalid filenames and existing-file collisions are handled without overwriting content silently. Cancelling folder or filename selection preserves the buffer and its pre-existing dirty flag without creating a storage record.
• After saving, Explorer and terminal reflect the new workspace file, and compilation is enabled only when the workspace contains at least one .cpp file.
• Starting a new project or opening a folder clears stale diagnostics, compile/run intent, terminal state, tabs, workspace state, and compiled-binary state.
• Existing workspace save, Save As, restore, and runtime write-back flows stay covered and working unless explicitly superseded above.

Verification

• npm run lint
• npm run test:e2e
• npm run build
• Browser smoke where the toolchain is available: npm run test:browser:chrome

Scope decisions

• The folder-picker-then-filename flow is required for the untitled state; do not substitute a native single-file Save As picker, because the extension needs a directory handle for Explorer, terminal listing, multi-file compilation, and workspace session persistence.
• Firefox local-file access support is intentionally out of scope for this issue. No Firefox fallback requirement is imposed.
• The default untitled document is deliberately ephemeral: do not restore its edits from extension/session storage.

[kbuffardi]

Plan decision recorded by Codex (GPT-5.6):

yes update the spec for 1 as "Save opens a folder picker, then the extension asks for a filename"

Updated the issue specification, plan, acceptance criteria, and implementation decision to require a folder picker followed by extension-managed filename entry. This preserves the directory handle required for Explorer, terminal listing, multi-file compilation, and workspace session persistence.

[kbuffardi]

Specification decision recorded by Codex (GPT-5.6):

Unsaved document model

On fresh launch and Start new project, the editor opens an ephemeral untitled document with
the Hello World template. It has no filesystem
path, directory handle, workspace membership, or persisted file record.

The untitled document must not appear in Explorer, terminal file listings, compile overlays,
diagnostics keyed to workspace paths, or session workspace metadata. It is not a file until
Save completes successfully.

The application must not write the untitled document to the host filesystem or extension/
session storage.

Updated the issue with this binding Unsaved document model, corresponding acceptance criteria, and an explicit no-storage implementation decision.

[kbuffardi]

Specification decisions recorded by Codex (GPT-5.6):

I deleted step 5 from the previous version of the issue. Adopt recommendation 2. Adopt recommendation 3 with additional spec that Compile buttons are disabled until a workspace folder has been selected and at least one .cpp file is within it. Overtly ignore recommendation 4 because Firefox local file access is unsupported and the browser is no longer recommended. For recommendation 5, any terminal commands (besides help) given should result in a terminal error message "Open a folder or save a file before using terminal commands." For recommendation 6 and 8, if the previous state did not have a selected workspace folder opened, a new session should start with a fresh default state (no workspace opened and the original Hello World code provided in an unsaved file tab); when starting a new project or opening a new folder, clear stale diagnostics, compile/run intent, terminal state, as well as tabs/workspace state. Adopt recommendation 7 to add negative storage tests. Update the issue accordingly.

Updated the specification and plan accordingly: explicit untitled tab identity; folder-backed Save; .cpp-based Compile and Compile & Run enablement; terminal gating outside a workspace; explicit fresh-state cleanup; no untitled storage/restore plus negative storage tests; and Firefox local-file support explicitly out of scope.

[kbuffardi]

Release metadata is prepared in commit 87d9155, with a metadata-only PR: PR #71.

The commit updates manifest.json, package.json, and package-lock.json to 0.4.5; it contains no application code changes. After PR #71 is merged, the release workflow will publish v0.4.5 from current main.