# Linking to timers, routines and selections

Eggtimer is being developed against the [Manifesto for Ubiquitous Linking technical requirements](https://linkingmanifesto.org/technical-requirements/). This page states the implemented contract and its boundaries; it is not an independent compliance certification.

## Three different resources

1. **Reusable setup**: `/5m`, `/Tea/for/3m`, named recipes, or `/#recipe=ENCODED_JSON`. Each opening creates a fresh local timer. Opening a recipe previews it; Start begins the routine. These URLs do not identify an existing execution.
2. **Individual browser timer**: `/t/UUID`. Creating a timer assigns this unique URL. Its state is saved privately in that browser. C / Copy link copies a portable setup for sharing. For makers → Copy private timer address copies this individual resource address. Reopening it in the same browser restores its stored state; a new controlling tab takes ownership and earlier views offer Use this tab. The ID stays stable through pause, reset and appearance changes. New timer/setup creates another resource. Up to 100 recent local timer records are retained. Clearing site data or evicting an old record removes access. A different browser/device cannot retrieve that local record and shows an explicit explanation. This is not cross-device synchronization or server scheduling.
3. **Server timer**: `/timers/ID`. HTTP/MCP creation returns `id`, `title` and `url`. Opening the URL asks for the private workspace API key and then reveals the selected timer. IDs alone grant no access. The record and link remain useful through state changes, subject to seven-day terminal retention. A workspace itself uses `/workspaces/ID`. Server records are not automatically created for ordinary browser timers.

A local timer link is a private reference. To give someone their own timer, use **Copy link / C**, **For makers → Copy shareable setup link**, or the link APIs. Neither kind of URL contains webhook or authentication credentials. Browser records are not uploaded as analytics; server timer storage is separate and opt-in.

## Deep selection without changing execution

A recipe's expanded, one-based step index is a secondary identifier: `/t/UUID#step=2`. Copy step link appears beside a recipe. Opening it reveals that step's label and duration; it does not jump to the step or restart the run. A portable recipe can also use `/#recipe=ENCODED_JSON&step=2` to select a step in its preview. The primary resource address omits the selection. This is a step index in an immutable recipe snapshot, not a promise that edits/reordering preserve the meaning of an old index.

## Browser linking API

The loaded timer exposes a documented JavaScript API, with no extra library:

```js
const context = window.LittleTimer.getLinkContext();
// context.resource: {id, name, uri, scope}
// context.selection: null or {name, index, uri}
// context.definition: {name, uri} for a reusable setup
// context.execution: {id, running, synchronized_across_devices:false}
```

`scope` is `this-browser` for a stored local timer and `portable-definition` before a resource is created. `getLinkContext()` reads the current resource and nested selection without starting anything. `window.LittleTimer.revealResource(uri)` navigates to a same-origin Eggtimer link; its normal opening behavior applies. `window.LittleTimer.copySetupLink()` copies the reusable definition. Do not execute navigation or timer creation without the person's intent.

Browser automation, accessibility tools and linking utilities can also read the page title and address, and use C or the visible copy controls. Keyboard shortcuts do not intercept text editing, system shortcuts or an open dialog. Export/import recipes as bounded JSON through Build your own; APIs create them with user-specified fields and return the address.

## HTTP and MCP linking API

POST `/api/timer-link` with `{"duration":"5m","label":"Tea"}` returns a reusable timer URL. POST `/api/recipe-link` with `{"recipe":RECIPE_OBJECT}` returns a portable routine URL. Public MCP `create_timer` / `create_recipe` perform the same operations. Neither starts a run.

Authenticated POST `/api/server-timers` or MCP `create_server_timer` creates a real server resource and returns its stable URL and title. GET status, MCP `get_server_timer` and workspace listing return that same URL. The authenticated browser view reveals the resource by URL. There is no public access bypass, automatic hook activation, or browser-state inspection through public MCP.

## PWA and app addresses

The PWA uses these same HTTPS addresses; no custom app scheme or ID conversion is needed. UUID / server ID maps directly to the documented web path, and vice versa. PWA installation does not synchronize browser-local storage across devices or guarantee phone background alarms.

## What remains

Links respect retention and access boundaries. Renaming a server timer is not yet an API operation. There are no indefinitely retained server bookmarks, public timer viewers, per-beat server events, or deeply selected server recipe executions yet. Browser timer controls synchronize between local views by storage events; this is best-effort same-browser coordination, not distributed consensus or multi-device collaboration. We do not claim every future resource type is covered before its API and link behavior are implemented and tested.