Skip to content

armgit / mimik

Public Imported from GitHub
0

🎬 A browser extension and desktop app that turns your clicks into step-by-step guides with annotated screenshots πŸ“–

docs: record the narration restart and transcript delete invariants

davbio951b44b0a72e
diff --git a/AGENTS.md b/AGENTS.md
index 9ea8bdc..27b622f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -198,6 +198,14 @@ table (Dexie `version(4)`) *before* it applies anything to steps β€” a recording
attributed is exactly the case this exists for, and it writes no step at all, so `saveTranscript`
announces itself on the guides channel rather than relying on `applyNarrationToSteps` to do it.
+`VOICE_RESULT` carries an explicit `final` flag, and `applyNarration` reports `idle` and settles the
+pending promise only on that flag. It used to infer finality from `transcribingGuideId`, which the
+background sets *after* `stopVoiceCapture` resolves β€” but the host calls `deliver()` synchronously
+whenever there is nothing left to transcribe (no steps, or every second already flushed), so the
+result could arrive first, be read as a mid-recording flush, and leave the panel spinning on
+`'transcribing'` forever. That is why the guide claims the transcription and calls
+`markNarrationPending()` *before* awaiting the host, and releases both if the host refuses.
+
One row per transcribed slice, because mid-recording flushes land separately from the tail.
`flushedUpToSeconds` in the voice host guarantees the slices never overlap, so `mergeTranscripts`
(`core/guides/transcript.ts`) can order them by wall clock with nothing to de-duplicate. The
@@ -215,8 +223,11 @@ when `hasTranscript` says there is one β€” which is re-read on every guide reloa
is still running when the dashboard opens after a recording. An unattributed line offers to append
itself to the nearest step: `nearestStepId` looks **forward** first, since onboarding asks users to
say what they are about to do and then do it. Accepting that writes the step onto the line
-(`attachTranscriptLine`, flagged `addedByHand`) as well as into the description, so the line reads as
-used from then on and a second visit to the panel cannot append the same words twice. Restoring that
+(flagged `addedByHand`) as well as into the description, so the line reads as
+used from then on and a second visit to the panel cannot append the same words twice.
+`addTranscriptLineToStep` does both writes in one Dexie transaction, and re-reads the line inside it:
+done separately, a throw between them left the words in the step with the line still reading unused,
+and a double click appended them twice. Restoring that
step's spoken original deletes the appended sentence, so `restoreNarratedDescription` releases the
lines it just wiped out and they return to unused β€” otherwise the panel would claim a step still
carries words it no longer has, with no way left to re-add them. Only hand-added lines are released;
@@ -226,11 +237,21 @@ Privacy is the cost of keeping this. A verbatim transcript is more sensitive tha
smart blur cannot reach speech, so a password read aloud lands in it as plain text. It is therefore
local-only: never in an exported guide, deletable on its own from the panel β€” which also clears
`narratedDescription` from the steps and from the snapshots that copied them, so β€œgone for good” is
-true β€” and swept by `permanentlyDeleteGuide` alongside snapshots. `mergeGuideInto` re-keys
-transcripts onto the guide it merges into and remembers the redirect, and `saveTranscript` resolves
-the owning guide before it writes β€” by that redirect, or by the guide a line's step now sits on β€”
-because an insert-recording deletes its staging guide before narration lands, and a slice where
-nothing was attributed has no step to resolve through. Stripping the spoken text rewrites the stored
+true β€” and swept by `permanentlyDeleteGuide` alongside snapshots. Clearing `narratedDescription` is
+not enough on its own: a step narration wrote holds the same words in `description`, and descriptions
+go into every export while transcripts go into none, so `forgetSpokenWords` also puts any step still
+sourced `narration` back on its rule-based text (`buildFallbackDescription`, source `heuristic`), and
+strips the sentences an `addedByHand` line pushed into a step β€” those are stamped `manual`, so the
+source alone would have left verbatim speech behind. A description the user or the AI wrote is
+otherwise left alone. `mergeGuideInto` re-keys transcripts onto the
+guide it merges into and records the redirect in the `guideMerges` table (Dexie `version(5)`, swept by
+`permanentlyDeleteGuide`), and
+`saveTranscript` resolves the owning guide before it writes β€” by the guide a line's step now sits on,
+or by walking that redirect chain β€” because an insert-recording deletes its staging guide before
+narration lands, and a slice where nothing was attributed has no step to resolve through. The
+redirect is a table and not module state in `core/guides/service.ts` on purpose: the only path that
+reads it is the tail transcription after a merge, and MV3 evicts the background worker after about 30
+seconds idle, so an in-memory redirect dropped the transcript with no error and no retry. Stripping the spoken text rewrites the stored
snapshot steps, so `deleteTranscripts` recomputes each `contentHash` too, or version history would
stop collapsing two identical saves into one row. Nothing was added to any export path, and nothing
should be.
@@ -392,6 +413,9 @@ Font: Poppins (loaded via `@fontsource/poppins`).
- **Content script injection** pings first, falls back to `chrome.scripting.executeScript()` for tabs without the script
- **`PAUSED` is a real machine state**, not a flag. It carries a `pauseReason` (`'blur' | 'manual'`) and deliberately does not handle `USER_ACTION`, so nothing can advance `stepCount` while the UI says capture is paused. `CaptureSession.syncWithBackground` only starts on `RECORDING`, so a frame that loads mid-pause stays idle instead of silently resuming. Background step writes are gated on `RECORDING` too, for a frame that missed the stop broadcast
- **Pausing also stops the microphone.** `pauseCapture` flushes and stops narration when it was live, and `resumeCapture` restarts it β€” otherwise speech during the pause is transcribed and attributed to the step captured after the resume. The mic toggle locks while paused, since narration cannot start outside `RECORDING`
+- **The restart has to outlive the flush.** Stopping narration leaves the phase on `'transcribing'` for a whole API round-trip, and `canStartNarrationNow` refuses that phase, so a single attempt on resume always failed and the mic never came back while the panel went on showing narration as enabled. `restartNarrationOnceTranscriptionSettles` retries while `isNarrationSettling()` holds, up to `NARRATION_RESTART_ATTEMPTS` waits on `whenNarrationSettled()`, then calls `reportNarrationLost` so the panel stops claiming the mic is on. It stops *immediately* when the phase is anything else: a start that failed on its own 8s timeout leaves the phase `'idle'`, and retrying there would call `startVoiceCapture` a second time, get `already-recording`, and `closeVoiceHost()` a host that had just started. It is deliberately *not* awaited by `resumeCapture` β€” the panel is waiting on that reply β€” so its rejection is caught rather than left unhandled
+- **`narrationWasLive` lives in the machine context**, not a module variable, because the worker can be evicted while the recording sits paused. Per the note above, a snapshot persisted before the key existed restores it as `undefined`, so it is read as `=== true`. Its *source* cannot be the module-level `phase` either, which an eviction resets to `'idle'`: `pauseCapture` calls `isNarrationLive()`, which asks the host when the phase says nothing, and counts `'transcribing'` as live so a second pause during the first one's flush does not lose the flag
+- **`claimTranscription`/`releaseTranscription` are a matched pair** and every path that reports `'transcribing'` uses them, `recoverNarration` included β€” a claim without `markNarrationPending` made `whenNarrationSettled()` resolve instantly and burned both restart attempts in one tick. They count outstanding transcriptions rather than holding one slot, because a pause followed by a stop claims twice; `releaseTranscription` returns whether it owned the claim, so a failed stop cannot report an error over a terminal `idle`
- **Pausing waits for the frames to drain.** `broadcastStopCaptureAndFlush` is answered only once each content script's queue is idle, because `CaptureController.stop()` enqueues the input session's finalize. `handleFinalizeInputStep` is therefore gated on "not IDLE" rather than `RECORDING`: it only ever completes a step the user finished before pausing, and `enterBlurMode` awaits the flush before opening the overlay so that screenshot cannot catch it
- **Navigation listeners treat `PAUSED` as live** (`navigation.ts:isLive`). `URL_CHANGED` has to keep flowing or the first step after a resume is stamped with the pre-pause URL, which Guide Me then replays to; injection has to keep running or a tab opened mid-pause is deaf to the resume broadcast
- **Blur mode pauses via that state**, and a top frame booting into `PAUSED`/`'blur'` re-opens the overlay, so a navigation mid-blur still has a Done button. `exitBlurMode` and the panel's Resume both broadcast `DISMISS_BLUR` before resuming, which closes the overlay but keeps the masks the user just picked; only the end of a recording sends `CLEAR_BLUR` to remove them