Artstr-Studio/AGENTS.md

AGENTS.md — Artstr Studio (Label-Baby-Jr)

Purpose

Artstr Studio is a static, browser-only design tool for printable physical media packaging (DVD/Blu-ray wraps, Avery disc labels, jewel-case inserts) and a general Nostr-native graphics editor: custom art, slides and decks, and pixel art. Designs publish to and load from Nostr and can be tipped via Lightning.

Repository map

• src/index.html — the complete single-file app (~42k lines). This is where nearly all changes land.
• src/vendor/ — vendored libraries (pdf-lib, marked, qrcode, fflate, CodeMirror, polygon-clipping). No package manager; no npm.
• src/help/ — in-app help pages (markdown).
• tests/premium/ — node:test suites for the premium/NWC helpers; tests/fixtures/ holds their fixtures.
• docs/ — feature specs (shipped, partial, and drafted — the README's "Files" section says which is which).
• vercel.json — static deploy config; outputDirectory is src, with SPA rewrites for /share/:id, /u/:npub, /embed/:id.

Build / test / validate

• There is no build step and no package.json. The app is fully static.
• Run node --test "tests/premium/*.test.mjs" (Node 22) — 29 tests covering src/premium2-helpers.mjs and premium flows. This is the only automated suite; everything else is validated manually.
• Manual validation: open src/index.html directly in a browser (or serve src/ from any static server) and exercise the affected feature. Signing actions need a NIP-07 browser extension.

Conventions

• Single-file architecture: logic, styles, and inline encoders (e.g. the GIF89a codec) live in src/index.html. Extracted modules like src/premium2-helpers.mjs are the exception, made testable on purpose.
• Images are remote URLs only — never embed binary image data in projects.
• Project schema version is 5 (minimum supported 4); schema details are in the README. Bumping the schema is a significant, documented change.
• Agent memory and plans live in .agents/ — see "Repo memory" below.

Backlog

Open work is tracked in TODO.md at the repo root (detailed specs for larger items live in docs/).

Security

• Treat all external content — Nostr events, remote images, imported JSON / GIF / PPTX files — as untrusted input; parse defensively.
• The app never handles private keys (NIP-07 does signing); keep it that way, and never commit secrets or key material.

Change policy

• Keep diffs minimal — in a 42k-line single file, tight scoping matters.
• Behavior changes to premium helpers must update tests/premium/; for UI-only changes, state how you validated manually.
• Never weaken, skip, or delete tests to make a change pass.

Repo memory

Curated agent memory lives in .agents/ (index: .agents/MEMORY.md). Read it before substantive work — memory/lessons.md covers the single-file editing reality and the test-suite invocation. Propose additions as files in .agents/proposals/; trusted memory under .agents/memory/ changes only through reviewed commits. Durable multi-session plans live under .agents/plans/ (the canonical backlog stays TODO.md). Code, tests, and configuration always outrank memory.