Home Organizer

A Vercel-hosted always-on home organizer with a Surface Pro display mode and a phone admin mode.

What changed in this version

• Events/tasks are saved to Vercel Blob only.
• Repeating tasks are stored as one master task with a repeat rule. The app no longer needs to create many copied tasks for weekly/biweekly/yearly repeats.
• If the server is busy/offline, phone/admin changes are saved locally on the phone first and retried automatically.
• Pending saves are kept in localStorage until Vercel accepts them.

Required Vercel setup

Create/connect a Vercel Blob store, then add this environment variable:

ADMIN_PIN=your_pin_here

Vercel Blob should provide BLOB_READ_WRITE_TOKEN automatically when the store is connected to the project.

Redeploy after changing environment variables.

URLs

Display mode for the Surface Pro:

https://your-project.vercel.app/?display=1

Phone admin mode:

https://your-project.vercel.app/?admin=1

Offline / busy-server safety

When you create, edit, complete, or delete a task from the phone, the app first stores the change on the phone in a pending queue. It then sends the change to Vercel. If Vercel is busy or the network fails, the task stays in the local queue and the app retries by itself after 15 seconds, then 30 seconds, 1, 2 and 5 minutes, and whenever the phone comes back online, the screen is tapped or the task list is refreshed. The automatic retries stop after that, because each attempt costs Blob reads; a save that is still stuck waits for the next refresh, tap or reconnect.

Open the hidden config menu by holding anywhere on the dashboard/admin screen. It shows the number of pending saves and has a retry button. It also reports tasks that are drawn on this device but that the server has not confirmed yet, so a task can no longer look saved while it is missing everywhere else. It names the app version this page is running and, when they differ, the version the server answered with — a page can sit open on the wall for days after a deploy, and "it is not doing the new thing" is usually just an old page. Reload it. If the server refused a new picture, that is reported there too, with the task it belongs to.

How concurrent saves are kept safe

All tasks live in one shared events.json in Vercel Blob, so every save is a read-modify-write of the whole file. Three things keep two devices saving at once from erasing each other:

• Every read is checked against the store. The Blob URL is CDN-backed and the path is reused on every overwrite, so for up to a minute after a save the CDN can still hand back the older copy of events.json. A unique query string does not get past it: the Blob CDN leaves the query out of its cache key (measured: ?v=<random> comes back as a cache HIT with the same age). So every read is compared against head(), which answers from the Blob API rather than the CDN. The byte length has to match, and so does the store's ETag (an MD5 of the content). Length alone used to let a same-length older copy through — moving a task from 10:00 to 11:00 keeps the length — and a save built on it silently undid that move.
• A write is never built on a replayed copy. If a read cannot be confirmed as current, the save answers 503 instead of rewriting the whole file from an old snapshot. That one rule prevents the worst failure this app can have: rewriting events.json without the tasks and pictures added since the copy was made — and it also stops a 404 Event not found for a task that plainly exists, which the phone would treat as permanent and drop the edit.
• Writes are confirmed against the store, not against a cached read. After each write, head() is asked whether the stored file is the exact document just written (same byte length and same MD5 ETag). If it is, the write is done — no CDN read involved. Otherwise the document is read back, and the answer is one of three, each handled differently:
  • the change is there → done;
  • a newer document is stored without the change → another device really did overwrite it, so the change is re-applied on top of the winner, up to three times;
  • every read still answers with a copy older than the write → nothing has replaced it and only the reading side is behind. The write stands. This used to answer 503 "another device saved at the same time" for a change the server had in fact stored, which left it queued on the phone forever, and every later change stuck in the queue behind it.
• A failed read never becomes a write. Blob trouble answers 5xx rather than overwriting the file with a guess, and only genuine validation problems (missing title or start) answer 4xx.
• One stuck change does not hold up the others. When the server refuses a change, the phone keeps it queued and moves on to the other tasks in the queue; only further saves of that same task wait for it. A genuine network failure still stops the pass, since nothing else would get through either.

If a task still goes missing from the server shortly after it was accepted, the device that created it notices on its next fresh read and sends it once more. Past a ten-minute repair window it assumes the task was deleted from another device and stops drawing it, so a delete is never resurrected.

Repeating tasks

Repeating tasks use these fields on the single master event:

{
  "repeat": "weekly",
  "completedDates": ["2026-05-10"],
  "excludedDates": ["2026-05-17"]
}

The browser expands those into temporary occurrences for display only. The server keeps just the master task.

New in cleanup/refresh version

• Event images are no longer deleted the moment a task is deleted or its picture replaced. The reminder cron (/api/reminders-cron, twice a day) sweeps images that no task has referenced for 7 days, tracked in home-organizer/image-sweep.json. A picture lost to a bad save therefore stays in the Blob store for a week: find it under home-organizer/images/ in the Vercel Blob dashboard and paste its URL into the task's image field. The sweep never deletes anything when events.json cannot be read, and never deletes an image uploaded less than 7 days ago.
• A device holding an older copy of a task (it marks it done, moves its date, adds a reminder) can no longer swap that task's image for the old one it remembers, or clear it. It may still set a genuinely newer upload, so a resync from that device works as before.
• Display mode loads cached tasks instantly, then performs one fresh server refresh on page boot and at midnight, and picks up changes from other devices through the version marker (see Keeping every screen in step below).
• Desktop admin mode shows a large Back to normal view button so you can return to the Surface display after editing.
• If admin and display are open in two tabs on the same device, the display tab is notified immediately after a successful save. Across different devices the version marker carries the change (see below).

Keeping every screen in step

Every save the server confirms also rewrites a tiny marker, home-organizer/events-version.json, holding the stamp of the stored task list. Every open screen reads that marker straight off the Blob CDN every 30 seconds (and when it wakes, comes back online, is tapped, or the camera dimmer sees someone). Only when the marker has moved does it read /api/events.

Why this costs nothing against the Hobby limits:

• The marker is uploaded with a 30-day cache life, so while nothing changes the CDN answers from its cache and the browser gets a 304. Blob does not bill a cache HIT as an operation; it only counts as a CDN request (Hobby includes a million a month; one screen polling every 30 seconds is about 86,000).
• Overwriting the marker purges the CDN copy, so a change reaches every screen within about a minute: one billed cache miss on the marker, plus one task-list read per screen.
• events.json itself keeps its short cache life on purpose. The save path reads it through the same CDN, and a purge that went missing must not be able to hold a stale copy there for a month.

The timed reads stay as a safety net, but while the marker is being read the hourly one only actually runs every few hours, and a tap only looks at the marker unless the last full read is more than 15 minutes old.

When the server can only get the CDN's older copy of the task list it says so (fresh: false). The screen keeps what it has and asks again after 15, 30 and 60 seconds, instead of showing the old list and refusing to read again for a minute — which is what used to make a tap right after a change on the phone show nothing.

Every request the screens make is time-limited. One that never answered used to leave the screen believing a refresh was still under way, and from then on it never refreshed again until somebody reloaded it.

The marker does not exist until the first save after this is deployed. A screen that finds it missing asks the server to create it and falls back to timed reads for half an hour.

The wall display also reloads itself after a deploy, once it is back on the home view and nobody has touched it for a minute, so fixes reach it without anyone reloading it by hand. It does not do this while the page is in browser fullscreen (double-press on the clock), since a reload would drop fullscreen; the config menu says a reload is due instead. Fullscreen started by the browser or a kiosk mode is not affected.

The config menu shows whether live updates are working and when the last full read was.

Daughter periods are shared

The blue daughter periods in the month view, and every change to them, used to be stored only on the device they were made on, so a period moved on the phone never reached the wall display. They are now stored in events.json next to the tasks (as daughterPeriods), so every refresh a screen already does brings them along without an extra Blob read, and the marker carries their changes too.

• Each edit (move, delete, reset, add) is sent as one change and applied to what the store holds, so edits to different periods from two screens both survive.
• Edits go through the same pending queue as task saves: shown at once, kept on the device until the server has them. Saving needs the admin PIN, like completing a task on the display.
• The first time a device loads this version, its old device-only edits are sent to the server once. They only fill periods the server has no entry for, so a screen that is reloaded days late cannot overwrite newer edits made elsewhere. A device without the PIN saved keeps its old edits until it has one.
• Delete all tasks/events clears tasks only; the periods are kept.

Resyncing a stuck image

Sometimes one task keeps showing the calm placeholder while every other task shows its photo. The editor has a Resync image button under the image field for that. It only appears while editing a task that already exists.

What it does:

1. Takes the photo you picked in the file field. If you did not pick one, it downloads the photo the task currently points at, cache-busted, so it works from whatever Blob storage really holds right now.
2. Uploads it to /api/upload?force=1. A forced upload skips the reuse-by-content shortcut and writes a brand new path, so the picture comes back on a link nothing has cached.
3. Saves the task with the new link and waits for the server instead of handing the change to the background queue, then reads back what the server kept.
4. Reports one of three outcomes: confirmed, still queued (server busy — it retries by itself), or the server refused the link.

Why the forced upload matters: a normal upload hashes the file and reuses the existing blob for identical bytes. Re-uploading the same photo therefore returns the same URL — which is useless when the URL itself is the problem (the blob was deleted and re-created at that path, or a CDN/browser is holding a stale copy behind the one-year cache header). That is why uploading the same picture again never fixed the last stuck image, and why a resync mints a fresh path.

If the stored image cannot be downloaded at all — it was deleted from Blob storage — the button says so. Pick the photo again in the file field and resync; that path does not depend on the dead link.

Fysio, lege and MR tasks borrow an old photo

The physio, the doctor and the MR scanner come round again and again, and nobody wants to pick a photo for the twentieth one. So a task whose title names one of these and that is saved without an image is given a random picture from an older task of the same kind, instead of the calm placeholder.

• Which titles count: fysio, lege and mr, case and accent insensitive. fysio and lege count inside a longer word at either end, because that is how they are written down: Fysioterapi, Fysioterapeut, Tannlege, Legetime, Legevakt. A word that only happens to end in one of them (college, privilege) does not. mr is two letters, so it only ever counts as a word of its own — MR, MR-time, MR undersøkelse, and MRI — never the inside of some unrelated word, so Mrs and Mormor are left alone.
• Kinds never lend to each other. A fysio task is only ever given a fysio photo, an MR task an MR photo. If that kind has no photo yet, the task gets the placeholder: that is the better wrong answer. Kinds used to lend to each other so the first ever fysio task could show a lege photo — and that one borrowed photo then sat on a fysio card, was read back as a fysio photo, and was handed to every fysio task after it.
• A picture you pick always wins. The borrow only ever fills an empty slot; nothing decided by the upload, by the task's stored image, or by the stale-device rules is overruled by it.
• Which photo: a random one from the same kind, preferring a photo somebody actually chose over one that was itself borrowed, so a single picture cannot take over every card.
• The framing travels with it. Pan, zoom and the focus box come from the task the photo was borrowed from, which is the framing somebody once chose for that picture.
• Only live links. The picture is checked against Blob storage before it is handed on, so a task never inherits a dead link.
• The borrowed picture is stored on the task like any other image, so it stays put on later saves. Upload a photo for the task and the borrowed one is replaced. The editor says which is which under the image field.

What a borrowed picture remembers

imageInheritedFrom records the task the picture came from, and imageInheritedKeyword which kind it is. The kind matters because a borrowed photo keeps the kind of the task it came from, whatever the task carrying it is called: a fysio card showing a lege photo is holding a lege photo, and lending that on as a fysio photo is exactly how one stray picture reached every fysio card. Both marks live and die with the image they describe — a task that gets a picture of its own loses them.

Pictures borrowed before the kind was written down are traced back through imageInheritedFrom instead. An origin that can no longer be established — the task it came from was deleted — is treated as unknown: the picture stays where it is, but it is never lent on.

A borrowed picture of the wrong kind is let go on the task's next save, and the slot is filled with a photo of the right kind, or left to the placeholder. Only ever a borrowed one: a photo somebody chose is never taken away. Until that save the card keeps showing it, and the editor says so under the image field.

The rule lives in api/_image-rules.js (autoImageKeyword, autoImageKindOf, isMismatchedBorrowedImage, pickAutoImage) and is applied by api/events.js to whatever any device sends. The admin page holds a copy of the same rule so a task saved on the phone draws its borrowed picture straight away rather than a placeholder that swaps out a second later, and so a task saved with no signal still gets one. Keep the two in step.

Face-aware image cropping

When you upload a task image, the admin page tries to detect faces in the browser and saves a simple focus point with the event. The dashboard then uses that focus point for daily, selected, upcoming, and admin thumbnails so faces are less likely to be cropped out.

Email reminders

This version adds email reminders without adding a separate database.

What is included

• The task editor has a Use email reminders checkbox.
• Recipients are hardcoded to Therese and Thomas.
• You can choose Therese, Thomas, both, or none.
• The selected recipients are saved onto the task in Vercel Blob.
• The server sends a task-created email through Resend when a new task is created, then schedules the task-day reminder.
• A daily /api/reminders-cron job refreshes the schedule so repeating/future reminders stay covered.

Required environment variables

Add these in Vercel → Project → Settings → Environment Variables:

RESEND_API_KEY=re_your_resend_api_key
REMINDER_FROM=Home Organizer <[email protected]>
CRON_SECRET=make-a-long-random-secret
ORGANIZER_TIME_ZONE=Europe/Oslo

Keep your existing variables too:

ADMIN_PIN=your_pin_here
BLOB_READ_WRITE_TOKEN=created_by_vercel_blob

About the sender address

Resend requires a verified sending identity/domain for reliable sending. Use your verified domain in REMINDER_FROM, for example:

REMINDER_FROM=Home Organizer <[email protected]>

For quick testing, Resend accounts often allow sending to your own verified account address, but family reminders should use a verified domain.

How reminders work

1. You create or edit a task.
2. You tick Use email reminders.
3. You select Therese, Thomas, or both.
4. The task is saved to Vercel Blob.
5. The Vercel API sends a task-created email now.
6. It schedules another reminder for 08:00 on the task day.
7. If the task starts before 08:00, it schedules the reminder for 12:00 the day before with “Remember this task early tomorrow”.
8. The daily cron checks all tasks again and schedules upcoming repeating reminders.

The cron in vercel.json runs once per day:

{
  "path": "/api/reminders-cron",
  "schedule": "22 3 * * *"
}

That works with Vercel Hobby. The exact delivery time is handled by Resend scheduled emails, not by the once-per-day Vercel cron.

Manual cron test

After deploying, open this URL in your browser, replacing the domain and secret:

https://your-project.vercel.app/api/reminders-cron?secret=your_CRON_SECRET

A good response looks like JSON with ok: true.

Blob efficiency changes

This version is tuned to use far fewer Vercel Blob operations:

• The dashboard no longer polls /api/events every 10 seconds, 10 minutes, or 2 minutes. It watches the version marker on the Blob CDN instead, which is free while nothing changes.
• Events are cached in localStorage, so the screen renders instantly from the last known calendar and keeps working if Blob/API is temporarily unavailable.
• On page boot the app now performs one fresh /api/events?fresh=1 read so loading/reloading the dashboard gets the newest server data.
• After boot, fresh reads happen when the version marker moves, at midnight, and as a few-hourly safety net. Interactions are debounced and only look at the marker unless the last full read is old.
• A save of a task with no email reminders (before or after the save) skips the reminder bookkeeping, which used to cost a Blob read and a Blob write on every save. The reminder state is also no longer rewritten when a sync changed nothing.
• The display re-renders locally every minute so date/time/day changes still update without calling Blob.
• Normal /api/events reads still use short API/CDN caching and a small in-memory cache per serverless instance. Fresh boot/midnight reads bypass that cache on purpose.
• Uploaded images are optimized before upload, usually targeting about 650 KB instead of allowing multi-megabyte photos.
• Re-uploading the exact same image now reuses the existing Blob URL by hashing the file instead of creating duplicates.

Picking a day on the display

Tapping the clock opens the day selector in the left card. Picking a day there shows that day's task in the big hero panel on the right, and the selector stays up with the picked day outlined, so the next day is one tap away. The task is deliberately not repeated in the left card. If a day holds several tasks the selector shows the count and the hero cycles through them; flipping the hero gives complete / edit / delete for whichever one is showing. Tapping the clock again returns to today and brings the weather back.

YouTube from your phone

The wall display has a hidden panel by the clock. A slim handle sits on the left edge of the screen, level with the clock: pull it to the right and the panel slides out, like Android's edge panel. A tap on the handle only nudges the panel out and back to show that it wants pulling, so a stray touch on the edge opens nothing. Tap beside the panel, push it back left, or leave it for ten seconds and it slides away again.

The panel has one button, YouTube, which shows a QR code. Scan it and the phone opens a small page (this same site with ?ytsend=<session>) with a field for a link. Paste a YouTube link — watch, youtu.be share, Shorts, live or playlist, with any t= start time kept — and tap Play on the wall screen. The wall closes the QR code and plays the video in YouTube's own player. Another video shows a fresh QR code while the current video keeps playing underneath; the × closes the player.

• How the link travels. Through ntfy.sh, a free, no-signup pub/sub relay — the same one the car lockscreen uses. The phone posts the link to a topic named after the session, and the wall holds one open stream (/sse) to that topic while the QR code is up. Nothing goes through Vercel, so a video costs no Blob operations and needs no admin PIN.
• Why a stream and not polling. ntfy limits requests per address, and at home the wall and the phone share one. Polling every few seconds would spend the allowance the phone needs to send its link. If ntfy refuses a send anyway (429), the phone says so and the button can be tapped again.
• Who can send. An ntfy topic is public. The session id is 64 random bits, a new one for every QR code, the wall only listens while that code is up, and it only plays YouTube links — it checks the link again itself rather than trusting the phone. The worst a stranger who guessed a live id could do is put a YouTube video on the screen.
• Idle. A playing video is not an idle wall: while it plays it keeps both the five-minute idle reset and the camera dimmer away, since nobody touches the screen while they watch. Paused or finished, the usual five minutes apply and the idle reset closes it. A QR code left up closes the same way.
• What it loads. The QR library (from jsDelivr) and YouTube's IFrame API are only fetched the first time they are needed. The IFrame API is used instead of a bare embed because the wall has to know whether the video is playing. Some owners forbid playing their videos outside YouTube; the player says so instead of showing a black box.

Tent view on the iPhone Duo

Fold the iPhone Duo shut and stand it up like a tent, so its outer screen is landscape, and HomeDash turns into a full-screen slideshow of the next 7 tasks with their photos — the same one the car lockscreen opens. Swipe left and right between them, or leave it and it moves on every 30 seconds. Turn the phone upright or open it and the page underneath is back exactly as it was.

• Which tasks. The next seven in start order: what is on now, then what is coming. Finished ones drop off (a task without an end counts as one hour long), so do completed ones, and frequent repeats appear no further ahead than the wall display shows them. Each occurrence of a repeat is its own slide.
• Photos. Framed exactly like everywhere else in HomeDash (focus point and zoom from the editor). A task without a photo, or with one that is gone from Blob storage, gets the calm placeholder.
• How only the outer screen gets it. Both Duo screens are the same shape, about 1:1.45. Opened, the inner screen is as tall as the outer one and twice as wide, so held normally it is landscape too, and it can be drawn at the outer screen's size. It turns on only when all of these hold:
  • this is an iPhone Duo: the browser says iPhone, and the physical screen (screen.width/height) is phone-sized and between 1:1.34 and 1:1.6. Either Duo screen passes; other iPhones are long and thin (about 1:2.17). The reported screen is trusted only this far: after the phone is folded or opened it can go on describing the screen that was left until a reload;
  • the window is at most 2350 real pixels wide: the outer screen is 2034 across in landscape, the inner one 2670, however large those pixels are drawn. The window and pixel ratio always describe the screen in use now;
  • the window fits on the reported screen: a page on the inner screen that is still told the outer screen's size is wider than it;
  • the phone itself is turned on its side (90° or 270°). A tent is the folded phone stood on its long edge; opened and held normally the phone is upright, even though its inner screen is wider than tall;
  • the window is wider than tall.
• Rotation protection. Turning, folding or opening the phone is a burst of events, and for a moment the window, the pixel ratio and the turn angle can disagree. Acting on such a moment could flash the slideshow onto the inner screen during a turn, and a change that came without an event (or with its event ahead of the new readings) was missed. Now:
  • the slideshow only comes up once the same readings have held for 0.7 s, and goes away on the first reading that says no;
  • on a Duo the readings are also taken every second, not only on resize, turn, pixel-ratio change and return to the page;
  • the slides are placed in percentages of their own width and re-placed by a ResizeObserver, so a size change cannot leave the next photo peeking in.
• Rotation lock has to be off on the phone, or the page never turns to landscape. Added to the home screen, HomeDash runs without Safari's bars and the slideshow fills the whole screen.

Weather effects

The whole dashboard lives in index.html — the <style> and <script> blocks inside it are what the browser runs. There is no separate bundle to edit. (Two exported copies, script.js and inline.js, used to sit next to it; nothing loaded them, and two bug fixes were accidentally applied only to those copies and never reached the app. They have been deleted — put dashboard changes in index.html.)

The weather card paints an ambience layer (#weatherEffect) behind the readout:

• Every condition gets a full-card colour wash, so rain, snow, fog, sun and thunder are recognisable from across the room. The wash is on in both layouts — previously the effects were invisible whenever a task was showing.
• Particles are generated per condition: rain streaks and ground splashes, swaying snowflakes at three depths, drifting fog banks, layered clouds, a sun with a corona and slow rays, a moon with a star field, and lightning with a full-card flash.
• Day/night comes from Open-Meteo's is_day. At night the card swings dark and the readout flips to light text (.wx-dark).
• Wind above 7.5 m/s adds gust streaks and appends the speed to the description line.
• Particles move in container-query units so they cross the card itself, and they are only rebuilt when the sky actually changes — the minute-by-minute re-render no longer restarts every animation.
• prefers-reduced-motion keeps the wash and static sky but drops everything that moves.