Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,17 @@ Capture the window you’re building, mark what should change, and hand the resu

<br>

<p align="center">
<img src="docs/media/screens/A-capture.png" width="300" alt="ContextLens capture panel with the Tidewater browser window selected.">
</p>
<p align="center">
<img src="docs/media/screens/A2-recording.png" width="441" alt="The compact recording pill with Snapshot and Stop controls.">
<br>
<sub>Choose one window. Keep working while ContextLens captures its states. · ContextLens 0.3.1</sub>
</p>

<br>

## Your UI feedback shouldn’t need an essay.

You spot it straight away: the button that’s a few pixels off, the avatar that doesn’t line up, the helper text nobody can read. Explaining it is the slow part. Which screen? Which button? How far is “a little to the right”? You crop a screenshot, describe it in a paragraph, paste both into your agent, and do it all again on the next round.
Expand All @@ -39,10 +50,22 @@ You spot it straight away: the button that’s a few pixels off, the avatar that

**2 · Review.** Flip through the states you captured. Untick the ones you don’t need, and click the one that shows the problem.

<p align="center">
<img src="docs/media/screens/B-review.png" width="100%" alt="Review five captured Tidewater states, with the first state unticked.">
<br>
<sub>Keep the states that matter. · ContextLens 0.3.1</sub>
</p>

**3 · Mark Up.** Drag a box around the problem, or highlight it freehand, then write what should change. Each mark gets a stable ID such as `CL-001`, so you and your agent always mean the same thing.

**4 · Hand Off.** Save the package and copy the ready-made prompt. Paste it into Claude Code, Codex or another coding agent, and it starts with your words and your pictures.

<p align="center">
<img src="docs/media/screens/D-handoff.png" width="100%" alt="A saved Hand Off with both written instructions in the context preview and Copy prompt ready.">
<br>
<sub>Save the package. Copy the prompt. Get back to building. · ContextLens 0.3.1</sub>
</p>

<br>

## Why developers use ContextLens
Expand Down Expand Up @@ -86,6 +109,12 @@ Built with SwiftUI and ScreenCaptureKit, with a floating capture panel and point

Say you’re tidying up a **Share workspace** dialog. Its buttons stop short of the email field’s right edge, and one avatar sits lower than the others.

<p align="center">
<img src="docs/media/screens/C-markup.png" width="100%" alt="A Box around the dialog buttons and a Highlight over the misaligned avatar, each with a specific instruction.">
<br>
<sub>Box the buttons. Highlight the avatar. Give each mark one clear instruction. · ContextLens 0.3.1</sub>
</p>

1. Capture the browser window while you open the dialog.
2. In Mark Up, box the buttons and write: *“Align the action buttons with the right edge of the email field.”*
3. Highlight the avatar and write: *“Center this avatar vertically in its row, like the one above.”*
Expand Down Expand Up @@ -120,6 +149,15 @@ ContextLens prepares the context. Your agent makes the change in your codebase,

ContextLens is in public preview. The first stable release, v0.3.1, will add a drag-to-install disk image.

<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/media/screens/E-dmg-dark.png">
<img src="docs/media/screens/E-dmg-light.png" width="720" alt="The ContextLens Mac installer: drag ContextLens into Applications.">
</picture>
<br>
<sub>Drag ContextLens into Applications. · v0.3.1</sub>
</p>

### Homebrew

```sh
Expand Down
2 changes: 2 additions & 0 deletions Sources/ContextLensApp/CapturePanel.swift
Original file line number Diff line number Diff line change
Expand Up @@ -470,6 +470,8 @@ private struct RecordingPill: View {
HStack(spacing: 6) { Image(systemName: "stop.fill").font(.system(size: 10)); Text("Stop") }
}
.buttonStyle(.lens(.record, height: 36))
// Keep the complete action and its padding in the intrinsically sized pill.
.fixedSize(horizontal: true, vertical: false)
.disabled(model.stopping)
}
.padding(.leading, 8).padding(.trailing, 9)
Expand Down
28 changes: 28 additions & 0 deletions config/publication-policy.json
Original file line number Diff line number Diff line change
Expand Up @@ -905,6 +905,34 @@
"docs/media/readme/workflow-dark.png": {
"sha256": "42c5219a35608a40739f96bf0e3ab6820de4d32f9a20f8f35e23d9e3aa1ef86f",
"purpose": "Owned decorative README brand artwork rendered by Brand/readme/render.swift from repository branding and system fonts; pixels reviewed; depicts no application UI and is not a screenshot."
},
"docs/media/screens/A-capture.png": {
"sha256": "12795b4eb224d741d9f9b0c767c3e26ae308177080a6a699cb6d99bb37cc4ec6",
"purpose": "Owner-approved genuine ContextLens 0.3.1 screenshot: choose the fictional Tidewater window. Only fictional Tidewater content; metadata removed without changing pixels."
},
"docs/media/screens/A2-recording.png": {
"sha256": "67432f8266459d63b75e476c0ab6764983bd964ac37173f41516be48645dfefd",
"purpose": "Owner-approved genuine ContextLens 0.3.1 screenshot: genuine recording pill with full Stop label. Only fictional Tidewater content; metadata removed without changing pixels."
},
"docs/media/screens/B-review.png": {
"sha256": "7d17d48ca6b444d18e8e9fe8f8fa1abcca0069bc0321819d9a9916ccdbf18ad1",
"purpose": "Owner-approved genuine ContextLens 0.3.1 screenshot: review five genuine captured Tidewater states. Only fictional Tidewater content; metadata removed without changing pixels."
},
"docs/media/screens/C-markup.png": {
"sha256": "98791ae2e39ab2cdc90e55ac19342eb646a560eff89f1abec5621a0f308a3bc5",
"purpose": "Owner-approved genuine ContextLens 0.3.1 screenshot: two native marks with the requested instructions. Only fictional Tidewater content; metadata removed without changing pixels."
},
"docs/media/screens/D-handoff.png": {
"sha256": "7565ba3c4621207fd9f4cd02fc15f0c4f1bef7300d998841dadeb9a8c9592014",
"purpose": "Owner-approved genuine ContextLens 0.3.1 screenshot: actual saved Hand Off and context preview. Only fictional Tidewater content; metadata removed without changing pixels."
},
"docs/media/screens/E-dmg-dark.png": {
"sha256": "155ecf9dc6f8d8dd0f9db0f9b866f920df69864ac82ae8a0ab962d602a398835",
"purpose": "Owner-approved genuine ContextLens 0.3.1 screenshot: genuine Dark Finder installer with Twin Glass and real draggable icons. Owned installer artwork and system icons only; metadata removed without changing pixels."
},
"docs/media/screens/E-dmg-light.png": {
"sha256": "b5f8219a3c8cf9fbc569ad4801636ba35b347b359f849fbab9d66c669cb364d9",
"purpose": "Owner-approved genuine ContextLens 0.3.1 screenshot: genuine Light Finder installer with Twin Glass and real draggable icons. Owned installer artwork and system icons only; metadata removed without changing pixels."
}
},
"pathExamples": {
Expand Down
13 changes: 11 additions & 2 deletions distribution/dmg/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ Choose a fresh output path. Development images are local engineering artifacts,

The builder verifies the original bundle, copies with `ditto`, adds a real `/Applications` symlink and hidden multi-resolution background, creates an HFS+ UDRW staging image, and mounts it at a unique canonical `/private/tmp` path with `-nobrowse -noautoopen`. It writes only that volume's `.DS_Store`, detaches it, and converts to read-only UDZO (zlib level 9). Final promotion uses an exclusive hard link, so even a concurrent build cannot overwrite published bytes.

Validation checks the UDIF checksum (`hdiutil verify`), filesystem (`diskutil verifyVolume`), bundle identity/version/deployment/architecture, strict signature, executable CLI and help, background alias, Finder metadata and icon locations. A throwaway `ditto` install copy is verified and compared with the original. Inventory comparison includes every file's SHA-256, executable bit and signed resource/Finder metadata. It ignores timestamps and quarantine, which are container/download properties. Attach and detach happen within a cleanup context even on validation failure; a forced detach fallback can target only the unique mount created by that context. No personal volume is searched by name.
Validation checks the UDIF checksum (`hdiutil verify`), filesystem (`diskutil verifyVolume`), bundle identity/version/deployment/architecture, strict signature, executable CLI and help, background alias, complete Finder picture settings and icon locations. Finder requires the fallback `backgroundColorRed`, `backgroundColorGreen` and `backgroundColorBlue` fields even with `backgroundType=2`. Omitting them causes Finder to ignore the picture and icon-size settings despite a valid alias. Verification rejects missing or malformed components. A throwaway `ditto` install copy is verified and compared with the original. Inventory comparison includes every file's SHA-256, executable bit and signed resource/Finder metadata. It ignores timestamps and quarantine, which are container/download properties. Attach and detach happen within a cleanup context even on validation failure; a forced detach fallback can target only the unique mount created by that context. No personal volume is searched by name.

## Regenerate the designs

Expand All @@ -42,6 +42,15 @@ python3 distribution/dmg/generate-background.py /tmp/contextlens-new-designs

`render.swift` draws repository-owned geometry and branding using AppKit and rasterized system typography. Xcode's `pngcrush` optimizes losslessly. No font files or third-party artwork are redistributed. Review both compositions, hero and labeled icon proof before copying them into the repository and adding their reviewed hashes to the publication policy.

## Remaining real Finder checks
## Real Finder checks

Metadata verification does **not** verify Finder rendering. On a disposable GUI Mac, open the actual DMG in light and dark appearances at 1× and Retina where available. Inspect text, precise icons/labels, arrow clearance, window bounds and background sharpness. Drag onto the actual Applications shortcut, eject and launch the installed copy. Record results against the exact candidate hashes using [isolated acceptance](../../docs/beta-acceptance.md). Do not overwrite the owner's installation or capture private desktop content.

After capturing only the actual Finder installer window without its shadow, check the rendered artwork as well:

```sh
swift distribution/dmg/verify-finder-background.swift /tmp/Finder-light.png distribution/dmg/assets/background@1x.png
swift distribution/dmg/verify-finder-background.swift /tmp/Finder-dark.png distribution/dmg/assets/background@1x.png
```

The check compares the wordmark, heading, subheading, arrow and footer with the owned artwork, allowing a system titlebar and 1×/2× captures. It excludes the draggable icons and labels. Missing artwork fails even when structural validation succeeds. This pixel check supplements full-resolution inspection; it does not establish icon functionality, installation, security authorization or maintainer acceptance.
5 changes: 5 additions & 0 deletions distribution/dmg/dmg.py
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,9 @@ def configure(mount):
store['.']['bwsp'] = dict(ShowToolbar=False, ShowStatusBar=False, ShowSidebar=False,
ShowPathbar=False, ShowTabView=False, WindowBounds=BOUNDS,
ContainerShowSidebar=False, PreviewPaneVisibility=False)
# Finder requires the fallback RGB fields even when backgroundType selects a picture.
store['.']['icvp'] = dict(viewOptionsVersion=1, backgroundType=2, backgroundImageAlias=alias,
backgroundColorRed=1.0, backgroundColorGreen=1.0, backgroundColorBlue=1.0,
iconSize=104.0, textSize=13.0, labelOnBottom=True,
showItemInfo=False, showIconPreview=False, gridSpacing=100.0,
gridOffsetX=0.0, gridOffsetY=0.0, scrollPositionX=0.0,
Expand All @@ -93,6 +95,9 @@ def verify_layout(mount):
options = store['.']['icvp']
require(options['iconSize'] == 104 and options['backgroundType'] == 2
and options['labelOnBottom'] and options['arrangeBy'] == 'none', 'Finder icon layout differs')
require(all(type(options.get(channel)) is float and options[channel] == 1.0 for channel in
['backgroundColorRed', 'backgroundColorGreen', 'backgroundColorBlue']),
'Finder picture settings require fallback RGB color components')
alias = Alias.from_bytes(options['backgroundImageAlias'])
require(alias.target.posix_path == '/.background/background.tiff'
and alias.volume.name == 'ContextLens', 'Background alias points outside this volume')
Expand Down
51 changes: 51 additions & 0 deletions distribution/dmg/verify-finder-background.swift
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
// Check genuine Finder captures against the owned artwork, excluding draggable icons and labels.
// This checks rendered pixels only; a maintainer must still inspect the complete installer.
import AppKit

guard CommandLine.arguments.count == 3 else {
fputs("Usage: swift verify-finder-background.swift FINDER.png BACKGROUND@1x.png\n", stderr)
exit(2)
}
func load(_ path: String) -> NSBitmapImageRep {
guard let data = try? Data(contentsOf: URL(fileURLWithPath: path)), let rep = NSBitmapImageRep(data: data) else { fatalError("Cannot decode image") }
return rep
}
let capture = load(CommandLine.arguments[1]), artwork = load(CommandLine.arguments[2])
guard artwork.pixelsWide == 720, artwork.pixelsHigh == 440 else { fatalError("Unexpected artwork dimensions") }
let scale = Double(capture.pixelsWide) / 720
guard (0.9...2.1).contains(scale) else { fatalError("Unexpected Finder capture width") }
// Owned wordmark, heading, subheading, arrow and footer. Never sample actual Finder icons.
let patches = [CGRect(x: 40, y: 30, width: 220, height: 28),
CGRect(x: 40, y: 97, width: 340, height: 28),
CGRect(x: 42, y: 142, width: 340, height: 20),
CGRect(x: 320, y: 230, width: 80, height: 40),
CGRect(x: 200, y: 386, width: 320, height: 24)]
func rgb(_ rep: NSBitmapImageRep, _ x: Int, _ y: Int) -> [Double] {
guard let color = rep.colorAt(x: x, y: y)?.usingColorSpace(.sRGB) else { return [1, 0, 1] }
return [color.redComponent, color.greenComponent, color.blueComponent].map(Double.init)
}
var best = Double.infinity, bestOffset = 0, bestPatches: [Double] = []
// Include the system titlebar in the screenshot; discover its height rather than cropping pixels.
let lastPatchRow = patches.map { $0.maxY }.max() ?? 440
for offset in 0...64 {
guard Int((lastPatchRow + Double(offset)) * scale) <= capture.pixelsHigh + 2 else { continue }
let errors = patches.map { patch -> Double in
var error = 0.0, count = 0
for y in stride(from: Int(patch.minY), to: Int(patch.maxY), by: 2) {
for x in stride(from: Int(patch.minX), to: Int(patch.maxX), by: 2) {
let expected = rgb(artwork, x, y)
let actual = rgb(capture, Int((Double(x) + 0.5) * scale), Int((Double(y + offset) + 0.5) * scale))
for c in 0..<3 { error += abs(expected[c] - actual[c]); count += 1 }
}
}
return error / Double(count)
}
let mean = errors.reduce(0, +) / Double(errors.count)
if mean < best { best = mean; bestOffset = offset; bestPatches = errors }
}
let passed = best < 0.035 && bestPatches.count == patches.count && bestPatches.allSatisfy { $0 < 0.055 }
let report: [String: Any] = ["renderedArtwork": passed, "meanAbsoluteRGBError": best.isFinite ? best : -1,
"patchErrors": bestPatches, "titlebarPoints": bestOffset, "scale": scale,
"maintainerVisualReviewRequired": true]
print(String(data: try JSONSerialization.data(withJSONObject: report, options: [.prettyPrinted, .sortedKeys]), encoding: .utf8)!)
exit(passed ? 0 : 1)
2 changes: 2 additions & 0 deletions docs/final-0.3.1-candidate.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Final v0.3.1 candidate integration — 9 November 2026

**Historical pre-fix candidate; do not promote after the native visual fixes.** Genuine testing found a missing Finder background and truncated Stop label. Production/packaging corrections and approved media must be integrated before preparing a fresh candidate and repeating exact-byte acceptance. See [the screenshot kit](screenshot-kit/README.md).

**Prepared release work; publication and genuine interactive acceptance remain blocked.** Version 0.3.1/build 6, arm64, macOS 14+. Only v0.3.0-preview.1 is published. No passing human acceptance record exists.

## PR #1 review and integration
Expand Down
Binary file added docs/media/screens/A-capture.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/media/screens/A2-recording.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/media/screens/B-review.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/media/screens/C-markup.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/media/screens/D-handoff.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/media/screens/E-dmg-dark.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/media/screens/E-dmg-light.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Loading