Skip to content

armgit / kokon

Public Imported from GitHub
0

Edit photos by describing the change, on your own GPU. A free, open-source alternative to Nano Banana and ChatGPT image editing: photos stay on your computer, no daily limit. One installer for Windows, Mac and Linux sets up the best open model (Qwen-Image 2.1). MCP server for AI agents.

Docs: 0.11 routes in the HTTP API, phones in the remote-access guide, the browser's measured facts

Gabriele Lozupone12a2b8ffb731
diff --git a/docs/engineering-notes.md b/docs/engineering-notes.md
index 57f808c..bcf06dc 100644
--- a/docs/engineering-notes.md
+++ b/docs/engineering-notes.md
@@ -300,6 +300,27 @@ token budget with the output as in edits (`cap_for_sources`), each at most the r
(Standard 1 MP) and never larger than the output. In the app, **New image** with images added sends
compose; **Edit image** keeps today's edit/combine.
+## The browser UI on phones (0.11)
+
+Measured on an iPhone 15 (iOS 27, Safari and the home-screen app) and in Playwright at 390x844, dpr 3:
+
+- **Previews.** In a browser the stage, full screen, comparisons and the paint editor show
+ `/gallery|inputs/{id}/preview` (at most 1280 px, JPEG) while it is as sharp as the full image there
+ (`logic.ts` `stageFitsPreview`, `viewerWantsFull`); the full file loads once the zoom needs more pixels.
+ A 30-version project of 2048 px PNGs opened with 0.84 MB instead of 15.1 MB.
+- **No image-sized layers.** WebKit backs a composited layer at its untransformed size x the device scale
+ (`GraphicsLayerCA::updateRootRelativeScale` is disabled), so a 4096 px image laid out at its own size and
+ shrunk by a 3D transform cost ~150 MB per layer at dpr 3, and an edit's full screen (four such layers
+ while the image developed in) crashed Safari (WebContent at 744-799 MB in the iPhone's JetsamEvent log).
+ In a browser `ZoomPan` lays the content out at its drawn size with a 2D translate (`flat`); the desktop
+ app keeps the scaled layer.
+- **Status bar.** iOS 26+ ignores `theme-color`: the bar takes the colour of an opaque fixed element at the
+ top of the page, read at load; a home-screen app keeps the manifest's `theme_color` for good (so the
+ manifest has none). `StatusTint.tsx` is a 6 px strip at the top of the body (a 1 px one was not taken),
+ created anew at every colour change, which makes iOS read it again; black while full screen is open.
+- **Take Photo.** The file input stays in the page until it answers: iOS drops a detached one while the
+ Camera is open. Safari names camera shots `image.jpg`, which is how `PhotoReview.tsx` tells them apart.
+
## HDR
The source's ISO 21496-1 gain map is reused and faded out where the edit changed brightness by
diff --git a/docs/http-api.md b/docs/http-api.md
index d9a465e..b7e94fc 100644
--- a/docs/http-api.md
+++ b/docs/http-api.md
@@ -1,7 +1,10 @@
# Local HTTP API
-Kokon's service listens on `127.0.0.1` only. The desktop app, the MCP server and your own scripts
-all use it. The routes below are the ones registered in
+Kokon's service listens on `127.0.0.1`. The desktop app, the MCP server and your own scripts
+all use it. When access from other devices is on, a second address (port `39152` by default, every
+network interface) serves the browser UI to them, signed in with the password; the token does not work
+there, and a browser can't use routes that touch files by path or change folders, model files or network
+settings ([remote-access.md](remote-access.md)). The routes below are the ones registered in
[`crates/qls-service/src/api.rs`](../crates/qls-service/src/api.rs); request bodies are JSON unless
a row says otherwise.
@@ -114,6 +117,20 @@ can be read and changed; send it back as `prompt` with `"enhanced_from"` set to
| `limit`, `offset` | Paging |
| `sort` | `recent` (default) or `oldest` |
+## Projects
+
+The project list every device shares (kept in `projects.json` in the data folder). A version is a
+result (`"kind": "gen"`, `genId`) or an imported image (`"kind": "input"`, `inputId`).
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| GET | `/projects` | Every project, most recently changed first: `{"projects": [...]}`, each as `/projects/{id}` gives it |
+| GET | `/projects/{id}` | One project: its `meta`, its versions (`items`), the `selected` one |
+| GET | `/projects/{id}/records` | The records of all its versions in one answer: `{"generations": {...}, "inputs": {...}}` by id; versions deleted from the gallery are left out |
+| PUT | `/projects/{id}` | Save a device's copy: `{"project": {...}, "known": [keys]}` (`known`: the versions that device had seen, so a version added elsewhere meanwhile is kept). Answers with the merged project |
+| DELETE | `/projects/{id}` | Remove the project from the list (its images stay in the gallery) |
+| POST | `/projects/import` | Merge a list of projects in, once: what each app kept on its own before 0.11 |
+
## Models, upscalers, LoRAs and LUTs
| Method | Path | Purpose |
@@ -147,3 +164,7 @@ and they may change between versions.
| POST | `/backend/start`, `/backend/stop`, `/backend/restart` | Control the inference server |
| POST | `/session/heartbeat`, `/session/release` | A client registers or drops its lease on the service |
| POST | `/shutdown` | Stop the service |
+| GET, POST | `/remote` | Access from other devices: its state and addresses; turn it on or off, `{"enabled": true, "port": 39152}` (needs a password) |
+| POST, DELETE | `/remote/password` | Set or change the password (`{"password": "..."}`, every browser signs in again); remove it, which also turns access off |
+| GET | `/auth/session` | A browser: whether it is signed in and whether a password exists |
+| POST | `/auth/login`, `/auth/logout` | A browser signs in with the password (a session cookie) or out |
diff --git a/docs/remote-access.md b/docs/remote-access.md
index 1ff1234..d3a322d 100644
--- a/docs/remote-access.md
+++ b/docs/remote-access.md
@@ -92,8 +92,16 @@ your home network, then open the same address as at home.
## What is different in a browser
-- **Adding photos:** the + button, dropping files on the page or pasting. They are uploaded to Kokon.
-- **Saving:** the download button saves the image on the device you are using.
+- **The same projects everywhere:** every device sees the same list of projects, kept by the computer
+ running Kokon. A version made on the phone shows up in that project on the computer.
+- **On a phone** the interface has a layout of its own: your projects as the home screen, a project's
+ versions swiped sideways, the image's actions in one row, and a screen of its own for writing the prompt.
+- **Adding photos:** the + button, dropping files on the page or pasting; on a phone, pick from the photo
+ library or take a photo (a photo just taken is shown first, with a **Flip** button for selfies). They
+ are uploaded to Kokon.
+- **Saving:** the download button saves the image on the device you are using. On an iPhone over plain
+ HTTP it shows the image full screen: press and hold it, then **Save to Photos** (with HTTPS, the share
+ sheet opens instead).
- **Copying an image** needs HTTPS (or the computer itself at `localhost`); on plain HTTP the button
is hidden.
- Not available: show in folder, open the logs, LoRA and `.cube` files from disk, choosing model files