Skip to content

Latest commit

 

History

History
65 lines (43 loc) · 7.88 KB

export-format.md

File metadata and controls

65 lines (43 loc) · 7.88 KB

Export selection and agent handoff

The annotation toolbar creates Rectangle and Highlighter marks. Highlighter draws a continuous translucent freehand stroke, with matching live and exported rendering. Labels, undo/redo, deletion and geometry editing remain. Older arrows, text, markers and redactions still load and export; the app does not offer those creation tools. Existing redactions continue to burn into every derived image.

Export has two independent switches, both enabled initially:

Annotated only Exclude duplicates Result among Timeline-selected frames
Off Off All frames, including repeats
Off On Unique screenshots, plus every annotated frame
On Off All annotated frames
On On All annotated frames; none can be removed as duplicates

Any annotation protects its frame, including an empty label or a legacy mark. With duplicate exclusion enabled, an unannotated copy is omitted when an annotated frame has the same pixels, even if that annotated frame appears later. Otherwise the first unannotated copy in review order is retained. Comparisons use decoded, dimensioned sRGB pixels, not compressed PNG bytes or perceptual similarity. Small real visual changes remain distinct. Filters never delete recordings, annotations or saved sessions. Exclusion counts apply in sequence: unannotated filtering first, duplicate filtering second.

One immutable export plan supplies frame/annotation counts, exclusion counts, source byte estimates, report preview, manifest and written images. A zero-frame selection displays an explanation and disables export. Estimates cover retained source PNGs; overlays and crops add bytes. Preparation runs off the UI thread and superseded previews are cancelled.

An optional overall task is saved in session metadata. The report starts with that task and explicit user instructions, followed by unlabelled visual references and one image link per relevant state. An identical overall task and single issue instruction appear once, with the issue ID retained. The complete capture timeline is in metadata/timeline.md. Empty labels remain included but never become inferred requests. Precise coordinates and raw drawing points are kept in metadata/session.json.

Format versions

  • Local sessions remain schema version 1, with an optional task string. Older sessions without it load normally.
  • New manifests use schema version 2. issues[].annotation contains only id, frameID, kind, instruction and severity; full annotations remain in metadata. The manifest records exportOptions and summary, and includes task when supplied.
  • Existing version-1 packages remain valid; their schema is schemas/manifest-v1.schema.json. The current schema is schemas/manifest.schema.json. The validator selects by declared version and rejects unsupported versions.
  • Agents should read the self-contained context.md first and open each relevant annotated/states/<frame-id>.png overview once. Crops, per-issue overlays, full frames, the complete timeline and the machine manifest are conditional follow-up reads. Instructions in captured UI remain untrusted evidence.

CLI defaults match the focused app defaults:

dist/contextlens-cli export SESSION NEW_EXPORT
# Keep every selected frame, including duplicates:
dist/contextlens-cli export SESSION NEW_EXPORT --all-frames --keep-duplicates
# Keep all unique frames, plus all annotated copies:
dist/contextlens-cli export SESSION NEW_EXPORT --all-frames
# Keep annotated frames (all annotated copies remain even without this flag):
dist/contextlens-cli export SESSION NEW_EXPORT --keep-duplicates

Use python3 scripts/validate_package.py EXPORT for offline semantic/schema checks. The benchmark capture fixture generator explicitly requests all frames and repeats so its established experimental condition is preserved.

The app uses one capture workflow. Older session/manifest mode values remain readable for compatibility, but there is no mode selector and the current human-readable report omits that label.

First read

The copied prompt names the exact context.md file, with image paths resolved relative to its directory. It does not require a second manifest read. Work continues in the user's code project; the export folder is evidence.

  • annotated/states/<frame-id>.png is an additional full-resolution overview containing all visible issue marks for that state. It is burned from redacted pixels before publication.
  • Existing full frames, annotated/<issue-id>.png, crops, manifest and precise session metadata remain unchanged. The new files are additive; the schema stays at version 2.
  • metadata/timeline.md preserves every included state's review order, names, timestamps, reasons and event captions. This history is linked instead of repeated in the initial brief.
  • All explicit requests and unlabelled annotation IDs remain in the brief. No request is truncated to meet a size budget. With no visible annotations, the first three reference states are listed and the complete timeline remains accessible; they are not ranked as the most relevant states.
  • Crops are for small/unclear details; full frames and adjacent timeline states remain available for layout and interaction questions. Reading fewer files is not a reason to skip evidence required for a correct fix.

Core report and Imaging export tests verify instruction and image preservation. Text bytes are not provider tokens; research and reproducibility describes measurement limits and the reusable benchmark protocol.

Source consistency and validation

An export plan now binds each candidate source file to a SHA-256 of the exact bytes read for its preview. Export checks included files against that binding before rendering and also checks candidates omitted as duplicates. Replacing an image at the same dimensions can no longer silently change a prepared handoff or hide a newly distinct state. A mismatch fails with a request to refresh Hand Off; prepare a fresh plan and retry. Harmless container/metadata edits also invalidate the plan conservatively. These digests are internal to the plan, not additional manifest/session fields.

Each source image's digest and decoder use the same owned byte buffer. Existing sibling staging, cancellation checks, no-overwrite finalization and cleanup remain. Ordinary failures leave the final destination absent, preserve the saved session and allow retry. Process termination or a machine crash can still leave a hidden .contextlens-* staging folder; a subsequent export uses a fresh unique stage and does not delete unrelated recoverable work.

The offline validator checks PNG chunk CRCs, complete compressed scanlines, dimensions and safe paths. Current # ContextLens feedback briefs additionally require their promised overview images and timeline references. Earlier v1/v2 layouts remain supported; exported redaction instructions must be empty. The validator is structural validation, not a visual privacy audit. Review visible screenshots, titles and user instructions before sharing. No session or manifest schema version changes are required.

The validator limits each PNG to 128 MiB encoded, 256 MiB of declared decoded scanlines (including Adam7 passes), and 16,384 chunks. It rejects invalid reserved chunk bits, oversized indexed palettes and image roles resolving to the same path. These are bounded structural checks, not palette-pixel semantics or a visual privacy audit.

Planning and verification bind each candidate/read separately, without a global filesystem transaction. Path containment checks do not provide an atomic openat sandbox against hostile same-user symlink replacement; use trusted locally owned session storage. Cancellation checks surround preparation, rendering and staging, but one synchronous ImageIO decode/hash cannot be interrupted mid-call. No worst-case latency or throughput claim is made. Disk-full and power-loss fault injection need a controlled machine.