# IDEA.md – a tool of your own for collecting and laying out material from the web This is a self-contained brief. Give it in full to Claude Code (or a similar tool) to build an implementation of your own. It draws on Clipper, a tool for collecting text and images from the web and laying them out freely on a grid, built with Claude Code. ## 1. What to build A web tool with sign-in where you collect material from the web and arrange it freely. Models: Fabric and Are.na. Use cases: research before buying (products with prices and specifications), moodboards, and studying with flip cards. In Clipper: - **projects with documents**, and every document is a grid. You drag across empty cells to mark an area, and can move and resize the block afterwards - **documents and boards**: a document has 1–12 columns and a reading width, a board 24, 48 or 96 square cells across the whole window, with zoom. The same thing seen through different grids, and you can switch - **seven block types**: text in Markdown (with highlighted code blocks), image, checklist, PDF, audio, flip card and encrypted block - **a pasted address** becomes an image block and a text block with title, description, price and specifications - **a Chrome extension**: a panel filled in from the page (Alt+C), and a right-click for selected text or an image - groups, multi-select, copy and paste, undo, overlap per document, colours per document - **sharing** by email address (view or edit), invitations for addresses without an account, and a public link - archive, search, print, export, dark mode, a home-screen app on iPad - **a user only ever sees their own data**, and no self-registration ## 2. Stack and architecture What **matters** is marked; the rest can be swapped. - **The browser**: React 18, Vite and TypeScript. - **The server**: PHP 8.3 with no framework, mysqli and MariaDB. A `php:8.3-apache` container for development, Apache and PHP directly in production. - **Important: pure logic in modules of its own.** Placement, undo, selection, copying, highlighting – everything testable without a browser – in modules that import neither React nor anything browser-bound. Then Node can run the tests directly (`node --experimental-strip-types`), with no build step. - **Important: the grid in CSS Grid** with explicit `col_start/col_span/row_start/row_span` and rows of fixed height. A block is exactly the area you drew. - **Reading a page in two places**: on the server for pasted addresses and in the extension for the panel. The same questions, the same order, and a fix in one has an obvious counterpart in the other. - **Files outside the docroot**, served only by a script after an ownership or sharing check. What a file is is decided by its bytes, never by its name. - **All outgoing HTTP through one function** with the SSRF rules. - **Public ids**: no numeric id leaves the server. ## 3. Decisions that turned out to matter **Read the page in falling reliability.** JSON-LD (schema.org) first, then Open Graph, last the markup – spec tables, definition lists, images. Choose the image by score: `og:image` first, then the largest area. Read the dimensions from the image address (`_SL1500_`, `800x600`, `?w=1200`) and let alt text that names what the page is about weigh heavily. Sort out logos, icons and tracking pixels. Take a price only where the page states it as a price. **Text blocks grow their own area.** Don't let the rows grow with the text – then every block beside it is stretched. Let the block measure how much it clips and grow itself. **Measure layout rather than assert it.** Render the real stylesheet and the real markup in a headless browser and read the numbers back. **Encrypt in the browser.** PBKDF2-SHA256 turns the password into an AES-GCM key; the server stores only salt, iv and ciphertext, and checks the shape so that plain text can't slip into a block claiming to be encrypted. The password never leaves the computer and can't be recovered. **Flip cards with the text as large as possible.** Find the size by bisection against the question "does it overflow now?", as a pure function over a predicate. **Sharing as a level, not yes/no.** Access is `owner`, `edit` or `view`. Editors change the content; deleting, moving, sharing on and turning on a public link are the owner's. An invitation is a share that doesn't have an account yet. **"Remember me" in a table of its own** with `selector:validator`, where only the validator's hash is stored, rotation on every use and theft detection – with a grace window for the previous secret. ## 4. Pitfalls - **Build output outside the mounted directory.** If Vite writes its output one level up and only the web app's directory is mounted in the build container, everything vanishes when the container exits – although the build looks successful. Mount the project root. - **`php:8.3-apache` ships with `AllowOverride None`**, so `.htaccess` is ignored and the SPA's deep links stop working. - **Rows that grow with their content** stretch the neighbours. Fixed rows, and let the block grow. - **Every image candidate with the same score** leaves document order to decide – and an ad banner wins. - **The rendered image address is often a thumbnail.** A gallery names the original in an attribute of its own. - **HTML in JSON-LD.** Shops' descriptions contain tags; clean them, and let a tag become a space, not nothing. - **Parallel requests and rotating cookies.** A page load sends several requests with the same cookie; without a grace window a reload signs you out. - **An expired session gives a stale CSRF token**, even on the sign-in. Fetch a fresh token and try once more. - **PHP's default session is 24 minutes.** Set `session.gc_maxlifetime` and a `session.save_path` of your own. - **Chrome saves one password per address and username.** Several tools on the same domain collide; let a prefix (`clipper/name`) be stripped at sign-in. - **`"type": "module"` in a root `package.json`** turns every `.js` beneath it into ESM and can silently break CommonJS files the tests read. - **A home-screen app on iPad doesn't share cookies with Safari.** The first launch needs a new sign-in. ## 5. Requirements and measurements - A user never sees anyone else's data – tested in the smoke test. - No numeric id in any response. - Encrypted content is unreadable in the database and in an export. ## 6. How it's verified - Type checking and lint in the build; a lint error stops the build. - Unit tests in Node for the grid, undo, groups, copying, the flip card's size search, highlighting and how a clipping is worded. - Layout tests in a headless browser against the real stylesheet. - Page reading against fixtures, both on the server and in the extension. - An end-to-end smoke test against a development instance: sign-in, sessions, grid, boards, overlap, groups, colours, clippings, flip cards, encryption, images, archive, sharing, invitations and data isolation. ## 7. Way of working - **An issue board**, one issue at a time, with the verification in the closing comment. - **Write the design decisions and the reasons down** in the README, so the next change doesn't redo a decision that's already been tried. - **Every schema change in two places**: a numbered migration and the same change in the full schema. ## 8. The prompt > Build a web tool where I collect text and images from the web and lay them out freely on a grid: projects with documents and boards, blocks of the types [text, image, checklist, flip card and encrypted block], pasted addresses that become an image, a price and specifications, and a [Chrome] extension. [React and Vite] in the browser and [PHP with no framework and MariaDB] on the server, with sign-in and sharing. > > Read all of IDEA.md below first. > > Work like this: > 1. Split the build into issues and ask me about whatever is open. > 2. Put all logic that can be tested without a browser in modules of its own with their own tests, and measure the layout in a real browser. > 3. Write an end-to-end smoke test, and run everything after every change. > > [paste IDEA.md here]