Locus

A local vault for linked notes. The text stays in the browser.

Overview

Locus is a writing desk for one device. You write a note, type / for a block and @ for another note, and the same notes can sit on a canvas, feed a small reactive notebook, or answer a question in Atlas with the passage they came from.

There is no account. The vault is stored in the browser. Export is a markdown file you download on purpose.

The interface is in Portuguese.

Em português

Locus é um caderno que mora no navegador. Você escreve como num bloco de notas: / abre o menu de blocos e @ liga outra nota pelo nome. Um endereço vira mapa só quando você pede, com o caminho e os links para abrir em outro aplicativo. As mesmas notas vão para o canvas, para um caderno que executa pela dependência e para o Atlas. A resposta aponta o trecho de onde veio. Sem conta e sem nuvem: o texto fica neste dispositivo, e a rede só é chamada quando você cria ou abre um mapa. Exportar é um arquivo que você baixa de propósito.

Features

• Notes. The visual editor is the default. Type / for a block (figure, sticker, photo, camera, video, map, note link, heading, list, checklist, quote, divider, code) or tap +. Type @ to link a note by name. A reading view sits beside the note.

• Photos and video. Gallery, in-app camera, a short clip, drag-and-drop and paste. Images are resized on the device and kept in IndexedDB. Nothing is uploaded.

• Private notes. Trancar nota encrypts the note on the device (PBKDF2 and AES-GCM). The list shows a padlock and the title, or hides the title. A forgotten password cannot be recovered. Unlock lasts for the session, then locks again after inactivity, or with Trancar agora.

• Canvas. Each card is a whole note. Moving it does not copy the text. Lines follow the links between notes. A locked note does not preview its text.

• Notebook. A small interpreter (mean, std, chart, and the rest) runs cells by dependency, not by screen order.

• Graph. Note links drawn as a graph. Drag a node to pin it.

• Atlas. Local retrieval over the vault (n-gram vectors and BM25) with citations. Pattern tools such as extract_wisdom preview a note and write only after you approve. Locked notes stay out of search until they are open.

• On this device. Search, theme, focus mode, and the command palette (Ctrl+K or ⌘K). New note is Ctrl+N. Ajustes holds Ver código for the file view, off by default, and an optional device PIN.

• Figures. A note can hold an interactive instrument. Insert it from / or +, as a full figure or a sticker. The flight card, place alerts, and the full-screen map question follow the approach of Osiris (MIT, simplifaisoul): the same public feeds, fetched only when you open the card. Locus does not copy that project's code. Osiris watches OpenSky, ADS-B feeds, USGS, NASA EONET, NASA FIRMS, and Open-Meteo, and it lets you draw an area on a MapLibre map. Here that becomes a note, not a global dashboard.

• Flights. A number such as LA8084 offers Acompanhar voo, and Voo is in the / menu. The card names the airline, the airports, and the status. A live position, heading, and altitude appear on the note's map while the card is on screen, and the refresh pauses when it is hidden. If the plane is on the ground or out of coverage, the card says so. An arrival time is labelled as an estimate. Flightradar24 and FlightAware stay one tap away for the official record.

• Place alerts. With Alertas on, an open place card can show severe natural events (NASA EONET), earthquakes of magnitude 2.5 or more from the last week (USGS), today's weather (Open-Meteo), and active fires only when a NASA FIRMS key is set on the server. Coordinates sent to those public APIs are rounded to about a kilometre. Each line links to its source. Results are cached on the device.

• Ask the map. Mapa shows every place from unlocked notes, clustered. Type or speak a question. Without a key, a plain text filter still works. With the same key used by Proponha uma ideia, the model receives only place names, rounded coordinates, note titles, and a short snippet, never a locked note, and only after a one-time notice. Desenhar área collects what is inside into a new note called Roteiro and can export GeoJSON.

• Maps. Mapa in the / menu searches a place and drops a pin. A line that looks like an address can offer Mostrar no mapa, and nothing is looked up until you tap. Como chegar draws a walk, bike, or car route. Google Maps, Waze, and Apple Maps open as ordinary links. Tiles come from OpenFreeMap (OpenStreetMap data) and need no key. The public routing demo is used only when you ask for a route; an OpenRouteService key in Ajustes is optional and stays on the device. A locked note does not load a map until it is unlocked. The network is called only when you create or open a map.

Figures

A figure is a small machine whose working is the idea: a patch bay for linked notes, a composing stick for a merge, a press that waits for approval. Hover or the arrow keys move it. Tap the figure for a small toolbar: full size or sticker, animation on or off, a rotation slider, take apart, export, remove. An unknown figure stays in the note and says so. Nothing is fetched.

Insert one with / or +, or from the command palette. The opening note is a blank page. Como usar points at the canvas, the notebook, and the graph.

The drawings are Anatomy figures (MIT, Ryan), vendored at .agents/skills/anatomy with that license. This pack is SVG only, in the light Locus palette. WebGL and the 3D turn mode are not used. Generated example HTML and PDFs are left out; node examples/<name>/build.mjs in that folder rebuilds them.

Slug	Machine
wikilinks	Patch bay. One cord, two lamps.
crdt	Composing stick. Two slugs, no referee.
embeddings	Comparator. The score stays on the bench.
notebook	Balance train. Order follows dependency.
atlas	Fiche reader. The finger lands on a real line.
canvas	Drafting board. A card moves, the sheet does not copy.
approval	Press. The platen waits for the lever.
local-vault	Desk safe. Export is the slip drawer.

Stickers

Figurinhas, in the header, is a drawer of the same machines. Each one has a white edge, a soft shadow, and a small tilt. Na nota drops it into the open note. No canvas puts it on the board as its own piece: the canvas still draws note cards, and a sticker sits beside them so you can drag it. It is not a second copy of a note.

From the toolbar, a sticker can loop or hold still, and the rotation slider turns it a little, from -12 to 12 degrees. A full figure is the instrument; a sticker is the small card. Notes saved before this editor still open as the same cards.

Export stays on this device. From the note or the drawer: SVG, a transparent PNG at 512 and at 1024, and an animated SVG. The animation is the same place loop, written as SVG motion, so it needs no GIF or WebP encoder and stays sharp. prefers-reduced-motion freezes the live loop.

Propose an idea

Proponha uma ideia, in the figure picker, the Figurinhas drawer, and the command palette, asks for a machine in plain words. The model must answer with the same part list the other figures use: slabs, cylinders, screws, a moving layer, and a lift for taking it apart. The app checks that shape, refuses scripts, event handlers, external links and foreignObject, and only then draws it. A bad answer stays unsaved, with a retry.

The feature does nothing until you paste your own key. The key lives in this browser’s localStorage, labelled in the settings panel, and it is sent only to the provider you pick: xAI, OpenAI, or another HTTPS endpoint that speaks the OpenAI chat-completions format. There is a button to remove it. No key is shipped with Locus. Anthropic is not offered: its API is not a browser call of that shape. Nothing on the network runs until you press Gerar.

A saved figure is named from what you asked. It can sit in a note, the drawer, or the canvas, full size or as a sticker, still or animated. Minhas figuras renames or deletes it. Deleting it leaves the card, which then reads as an unknown figure.

Interface

Captured from the running app. The window frame is only for this page.

Palette

Taken from the app theme in src/styles.css.

Name	Hex	Role
Paper	#F3EFE6	Page
Warm	#FAF7F1	Raised surface
Line	#E2D9C9	Hairline
Muted	#6D655C	Secondary text
Ink	#1A1714	Text
Copper	#9C4520	Accent

Dark theme swaps the same roles: paper #12100E, ink #F3EEE6, copper #E39462.

The mark is the ring and copper point from public/favicon.svg.

Stack

React 19, TanStack Start and Router, Vite, Tailwind CSS 4, Radix, Zustand. The vault itself is client state persisted to localStorage.

Postgres is optional and unused by the notes. With DATABASE_URL, server code uses pg. Without it, an in-memory PGLite database can apply migrations/*.sql. The Better Auth schema lives in migrations/auth/ and is not applied to the note vault. Sign-in is off (config/app-env.json sets VITE_AUTH_ENABLED to false).

Atlas questions stay on the device until GEMINI_API_KEY is set on the server. With that key, a question and a few retrieved passages go to Gemini 4 Argon, and the reply has to quote those passages. Without the key, or if the call fails, Atlas uses the local answer. Pattern extraction can call the xAI API when XAI_API_KEY is set. Without that key, extraction stays on the local path.

Getting started

The live app is at locus-brown-delta.vercel.app. Every push to main redeploys it.

To run a copy locally, Node.js 22.

npm install
npm run dev

Open http://localhost:8080. The sample vault is already there.

cp .env.example .env   # optional
npm test
npm run typecheck
npm run build

Script	What it does
dev	Vite on 0.0.0.0:8080, with config/app-env.json applied
build	Production build, then db:migrate
db:migrate	Applies migrations/*.sql when DATABASE_URL is set. Skips otherwise
preview	Serves the production build
test	Migration, auth-flag, and library tests
typecheck	tsc --noEmit
lint / format	ESLint and Prettier

scripts/grok-pwa-plugin.test.mjs is the platform install-page suite. It assumes a blank template title, so it is not part of npm test once the app is named Locus and ships public/og.jpg.

Project structure

src/components/locus/   notes, visual editor, canvas, notebook, graph, atlas
src/lib/vault/          store, markdown, seal, notebook, retrieval, patterns
src/lib/media/          photos and video in IndexedDB, encrypted with a locked note
src/lib/auth/           optional Better Auth, off unless you turn it on
src/lib/db.ts           PGLite fallback or Postgres via DATABASE_URL
src/routes/             TanStack Start routes
migrations/auth/        Better Auth tables, opt-in
config/app-env.json     build flag: auth disabled
public/                 favicon and share card
.github/assets/         mark, wordmark, banner, palette

Roadmap

The opening page is a blank note. Search, the canvas, the notebook, the graph, Atlas, and the map all read that same local copy. Today the copy that matters is localStorage on this browser.

What the app already draws a line toward:

• Sync between devices without giving up the local copy
• Embeddings that stay on the device
• A license, when the author chooses one

Author

Wellington Vieira De Souza

License

This repository does not include a license. All rights stay with the author until one is added.