LensCycle

English | Chinese

Download Latest .scriptable | Latest Release | Changelog | Contributing

A cyberpunk-style manual day tracker designed for the Scriptable medium widget on iPhone.

LensCycle was originally built to track how many days a pair of contact lenses has actually been worn, but it is not limited to contact lenses. By changing MAX_DAY, you can use it to track any item that should only count up when you manually use it, such as care cycles, consumables, replacement intervals, medication rounds, or habit streaks that should not auto-increase by calendar date.

The visual style is inspired by Trauma Team from Cyberpunk 2077. The icon is embedded directly in the script as Base64, so the project stays lightweight and self-contained with no external asset downloads.

Quick Start

If you just want the fastest setup path:

1. Install Scriptable from the App Store.
2. Download the latest LensCycle.scriptable file and open it with Scriptable.
3. Add a medium Scriptable widget and set its script to LensCycle.

Why This Exists

Many "replace every N days" items should not be tracked by automatic calendar progression.

• Contact lenses should not keep counting on days you do not wear them.
• If you forget to log a day, you should be able to tap multiple times to catch up.
• Once the limit is reached, the widget should clearly tell you it is maxed out.
• The tracker should live on the Home Screen and stay fast, simple, and local.

LensCycle is built around that exact workflow:

• It only increments when you tap.
• It does not auto-increase while unused.
• It supports repeated taps for manual catch-up.
• It shows MAX at the configured limit.
• One more tap after max starts a fresh cycle.

Features

• Built for the Scriptable medium widget on iPhone
• Left panel tap to add +1 day
• Right panel tap on the Trauma Team logo to Purge and reset the record
• Displays the timestamp of the latest increment
• Stores data locally in a JSON file
• No network requests, no dependencies, no external icon file
• MAX_DAY is editable for any custom cycle length

Screenshots

Initial state

In use

Max reached

When the count reaches MAX_DAY, the widget displays MAX.

Purge confirmation

Tapping the Trauma Team logo opens a confirmation dialog before wiping the record.

Installation

1. Install Scriptable

Download Scriptable from the App Store on your iPhone:

• App Store: https://apps.apple.com/us/app/scriptable/id1405459188

2. Import LensCycle.scriptable

LensCycle.scriptable is a Scriptable export file that can be imported directly into the app.

Recommended import flow:

1. Download LensCycle.scriptable on your iPhone.
2. Open the file in the Files app.
3. Tap Share or Open In.
4. Choose Scriptable.
5. Scriptable will import the script automatically.

If Scriptable does not show up immediately:

1. Tap Share.
2. Tap More.
3. Enable Scriptable in the app list.
4. Open the file again with Scriptable.

3. Run the script once

After importing, open LensCycle in Scriptable and run it once manually.

This helps you:

• confirm that the import worked
• preview the medium widget layout
• verify that the UI looks correct before placing it on your Home Screen

4. Add the medium widget

Add a Scriptable medium widget to your iPhone Home Screen, or to the leftmost iOS Today View page:

1. Long-press on an empty area of the Home Screen.
2. Tap the + button.
3. Search for Scriptable.
4. Choose the medium widget size.
5. Add it to the Home Screen or Today View.

Do not use the small widget. This project's layout and left/right interaction model are designed specifically for the medium widget.

5. Assign the script

After adding the Scriptable widget:

1. Long-press the widget.
2. Choose Edit Widget.
3. Set Script to LensCycle.
4. Close the edit panel.

The widget will now render this project.

How To Use

Left side: add one day

Tap the Day N area on the left:

• the day count increases by 1
• the latest update timestamp is refreshed
• you can tap multiple times if you forgot to log earlier usage

After max: one more tap resets it

The default value is MAX_DAY = 14.

• when the count reaches 14, the widget shows MAX
• the next tap on the left panel resets the cycle to 0

That makes it a natural fit for bi-weekly contact lenses, while still working for any fixed-length usage cycle.

Right side: Purge reset

Tap the Trauma Team logo on the right:

• the script runs through Scriptable URL Scheme
• a Purge Log? confirmation dialog appears
• choosing PURGE force-resets the current record

Customization

Change the maximum number of days

Open LensCycle.scriptable and find:

const MAX_DAY = 14

Change it to any number you want, for example:

• 7 for weekly lenses
• 14 for bi-weekly lenses
• 30 for monthly lenses
• 90 for a quarterly supply or any longer cycle

Local data storage

The script stores its data in Scriptable's local documents directory as:

contactLensData.json

It keeps:

• the current count in day
• the most recent increment time in lastIncrementAt

That means:

• all data stays local
• no network is required
• the count does not increase unless you explicitly tap it

Implementation Notes

This is not just a static widget. It uses Scriptable's widget APIs and URL Scheme support:

• ListWidget builds the medium widget UI
• WidgetStack.url assigns tap actions to the left and right areas
• scriptable:///run?... triggers increment and forceReset
• args.queryParameters reads the action parameters
• Script.setWidget(widget) outputs the final widget

Because Purge needs a confirmation dialog, tapping the right side launches Scriptable to execute the action. That is expected behavior.

Good Use Cases

• contact lens wear tracking
• cosmetic lens care cycles
• razor blade replacement cycles
• filter or consumable replacement intervals
• medication, supplement, or care product rounds
• anything that should only count when you manually decide it was used

Use Cases Gallery

Here are a few practical examples beyond the default bi-weekly contact lens setup:

• Weekly lenses: set MAX_DAY = 7 for short replacement cycles
• Monthly lenses: set MAX_DAY = 30 for longer wear tracking
• Razor blade rotation: count only the days the blade was actually used
• Filter replacement: track active usage days instead of calendar days
• Medicine or supplement rounds: log only the days the item was really taken

LensCycle works best anywhere "days used" matters more than "days passed."

Troubleshooting

Why does the right side open Scriptable?

The right-side Purge action needs a confirmation dialog. Scriptable has to open the app to show that confirmation before wiping local data.

Why does the widget not add one day automatically every day?

This project is intentionally manual. It only increments when you tap the left side, so skipped or non-usage days are not counted.

Why can I not find Scriptable in the share sheet?

Open the iOS share sheet, tap More, then enable Scriptable in the app list. After that, try opening LensCycle.scriptable again.

Why is the small widget not supported?

The current layout and interaction zones are designed for the medium widget. A small widget does not provide enough space for the left counter area and the right reset area to stay clear and reliable.

Where is my data stored, and how do I fully clear it?

LensCycle stores its local state in contactLensData.json inside Scriptable's documents directory. You can clear it by using the Purge action, or by removing the file manually from Scriptable's local storage if needed.

Compatibility

• Intended for iPhone and iOS users of Scriptable
• The current layout is designed for the medium widget
• Small widgets are not recommended for this interaction model
• Widget refresh timing is still subject to iOS scheduling
• Tap actions run immediately when the widget interaction is triggered

References

• Scriptable App Store: https://apps.apple.com/us/app/scriptable/id1405459188
• Scriptable Docs / ListWidget: https://docs.scriptable.app/listwidget/
• Scriptable Docs / WidgetStack: https://docs.scriptable.app/widgetstack/
• Scriptable Docs / args: https://docs.scriptable.app/args/
• Scriptable Docs / URLScheme: https://docs.scriptable.app/urlscheme/
• Scriptable Docs / Script: https://docs.scriptable.app/script/

License

This project is released under the MIT License.