@unbase-app/layer 0.0.0-stage → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Jens van der Blij
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,401 @@
1
- # Temporary Holding Version
1
+ <div align="center">
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ # @unbase-app/layer
4
+
5
+ **Review and edit an Astro site on the site itself. Add `?comment` to any address.**
6
+
7
+ [![npm](https://img.shields.io/npm/v/@unbase-app/layer)](https://www.npmjs.com/package/@unbase-app/layer)
8
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
9
+ [![Node](https://img.shields.io/badge/node-%3E%3D22.12-339933.svg)](#requirements)
10
+
11
+ </div>
12
+
13
+ The layer is the part of [Unbase](https://unbase.app) that runs on a site itself. Open any page with
14
+ `?comment` and a toolbar appears over it:
15
+
16
+ - **Comments on elements.** Click anything to pin a comment to it, reply in a thread, mention
17
+ someone with `@`, resolve it. A pin finds its element again after the page changes.
18
+ - **Review together.** See who else is reviewing, where their cursor is and what they are writing.
19
+ Follow someone across pages, or present so that everyone follows you.
20
+ - **Edit in place.** The team changes text, page settings, images and lists on the page. Changes
21
+ are shared drafts, and **Publish** puts them live as one commit.
22
+ - **Comments to changes.** A CLI hands the comments to a coding agent, with the component and
23
+ source file behind each pin and a screenshot at the reviewer's window size. The agent posts its
24
+ reply, with before and after images, back under the pin.
25
+
26
+ Ordinary visitors load none of it: a few lines on every page check for `?comment` and only then
27
+ load the layer. It renders in a shadow root, so the site's CSS and the layer's never meet. The
28
+ backend (accounts, roles, comments, Realtime, publishing) is Unbase's.
29
+
30
+ > **Formerly `@jens4m/comment-modus`.** Version 2.0 is the same layer under its new name. See
31
+ > [Moving from `@jens4m/comment-modus`](#moving-from-jens4mcomment-modus).
32
+
33
+ ## Contents
34
+
35
+ - [Quick start](#quick-start)
36
+ - [Requirements](#requirements)
37
+ - [Configuration](#configuration)
38
+ - [What the package contains](#what-the-package-contains)
39
+ - [How it works](#how-it-works)
40
+ - [The CLI](#the-cli)
41
+ - [Demo mode](#demo-mode)
42
+ - [Theming](#theming)
43
+ - [Content Security Policy](#content-security-policy)
44
+ - [Moving from `@jens4m/comment-modus`](#moving-from-jens4mcomment-modus)
45
+ - [Development](#development)
46
+ - [Releasing](#releasing)
47
+ - [Limitations](#limitations)
48
+ - [Licence](#licence)
49
+
50
+ **Reference:** [Edit mode](docs/edit-mode.md) · [The backend: database, roles, e-mail](docs/backend.md) ·
51
+ [Comments to changes: the agent workflow and the Operator](docs/operator.md)
52
+
53
+ ## Quick start
54
+
55
+ A site connected to Unbase through [`@unbase-app/astro`](https://www.npmjs.com/package/@unbase-app/astro)
56
+ already has the layer: run `npx @unbase-app/cli init` and skip to step 4. To add it on its own:
57
+
58
+ **1. Install**
59
+
60
+ ```bash
61
+ npm install --save-exact @unbase-app/layer
62
+ ```
63
+
64
+ **2. Add the integration** in `astro.config.mjs`
65
+
66
+ ```js
67
+ import { defineConfig } from "astro/config";
68
+ import react from "@astrojs/react";
69
+ import layer from "@unbase-app/layer";
70
+
71
+ export default defineConfig({
72
+ integrations: [react(), layer({ project: "1b2c…-uuid" })],
73
+ });
74
+ ```
75
+
76
+ `project` is the only required option: the id of the site's Unbase project, or its slug.
77
+
78
+ **3. Point it at Unbase**
79
+
80
+ ```dotenv
81
+ PUBLIC_SUPABASE_URL=https://<ref>.supabase.co
82
+ PUBLIC_SUPABASE_ANON_KEY=<anon key>
83
+ ```
84
+
85
+ Put these in `.env` locally and in the host's environment variables for production. Both are public
86
+ by design: they end up in the browser, and every right is enforced by Row Level Security.
87
+
88
+ **4. Invite people** to the project in Unbase, or set its sign-up mode to open.
89
+
90
+ **5. Open the site with `?comment`.** The layer asks for an e-mail address and mails a sign-in code.
91
+ The mode then stays on for the browser session; × in the toolbar removes the layer until the next
92
+ `?comment`.
93
+
94
+ ## Requirements
95
+
96
+ | | |
97
+ |---|---|
98
+ | **Astro** | 5 or newer, with `@astrojs/react` |
99
+ | **React** | 19 (`react`, `react-dom`) |
100
+ | **Node.js** | 22.12 or newer |
101
+ | **Unbase** | the site is a project in Unbase. Every site shares Unbase's Supabase project. |
102
+ | **The CLI only** | the Supabase CLI and `gh` signed in, Google Chrome, and `sharp` and `playwright-core` in the site's devDependencies |
103
+
104
+ ## Configuration
105
+
106
+ ```js
107
+ layer({
108
+ // The Unbase project: its id, or its slug.
109
+ project: "1b2c…-uuid",
110
+
111
+ // "en" (default) or "nl": every string a reviewer reads, and date formats.
112
+ language: "en",
113
+
114
+ // Unbase's Supabase project. Default: PUBLIC_SUPABASE_URL and PUBLIC_SUPABASE_ANON_KEY.
115
+ supabase: { url: "https://….supabase.co", anonKey: "…" },
116
+
117
+ // Load the hosted layer from layer.unbase.app instead of building it into the site.
118
+ // The site's build then carries only the configuration and one import.
119
+ layerUrl: "https://layer.unbase.app/v1/loader.js",
120
+
121
+ // Component path → readable name, for pin labels and thread headers. keyFromPath()
122
+ // turns "src/components/layout/Hero.astro" into "layout/Hero".
123
+ titles: { "layout/Hero": "Hero", "ui/Button": "Button" },
124
+
125
+ // Components that say nothing about what is on screen (a Section, an animation),
126
+ // left out of a pin's component chain. A regex on the component path.
127
+ wrappers: "^(motion/|layout/(Section|Container)$)",
128
+
129
+ // Components in the chain that never name the place: a click on the hero's button
130
+ // is "Hero › Button", not "Button".
131
+ atoms: "^ui/(Button|Heading|Image)$",
132
+
133
+ // The data-c marker on every .astro component's root element. "always" (default)
134
+ // or "preview" (dev servers and previews only), false, or { dir, skip, when }.
135
+ componentMarker: { skip: ["dev/"] },
136
+
137
+ // Edit mode: the content folder whose JSON the team edits on the page.
138
+ edit: { content: "src/content" },
139
+
140
+ // The page tree for the team; exclude is a regex on paths to leave out. false: off.
141
+ pages: { exclude: "^/components/preview/" },
142
+
143
+ // The repository's main branch. A preview of any other branch is a working version,
144
+ // and shows only its own comments.
145
+ mainBranch: "main",
146
+
147
+ // An SVG path for the Operator's avatar. Default: a generic icon.
148
+ logo: { viewBox: "0 0 24 24", path: "M…" },
149
+
150
+ // Overrides for the layer's design tokens, by name without --cm- (see Theming).
151
+ theme: { font: "var(--font-body)" },
152
+
153
+ // Minutes away after which unread notifications go out by e-mail. Set it to the
154
+ // same wait as Unbase's notification-mail for the project.
155
+ emailAfter: 15,
156
+
157
+ // false: no /version.json and no "new version, please reload" prompt.
158
+ versionRoute: true,
159
+ });
160
+ ```
161
+
162
+ Every option is typed in [`src/astro/index.d.ts`](src/astro/index.d.ts).
163
+
164
+ ## What the package contains
165
+
166
+ | Import | What it is |
167
+ |---|---|
168
+ | `@unbase-app/layer` | The Astro integration (default export), and `keyFromPath()` |
169
+ | `@unbase-app/layer/start` | The layer itself, compiled to plain JavaScript. The integration loads it; a site never imports it. |
170
+ | `@unbase-app/layer/page` | `pageTools()`: placing and finding pins. Unbase's editor runs the same code in its canvas. |
171
+ | `@unbase-app/layer/edit` | `editTools()`: matching text on the page to the content, and the editing session. Shared with Unbase's editor too. |
172
+ | `@unbase-app/layer/version` | The `/version.json` route |
173
+ | `unbase-layer` | The CLI (`comment-modus` is the same command under its old name) |
174
+ | `skills/` | Claude Code skills for the agent workflow ([docs/operator.md](docs/operator.md)) |
175
+
176
+ ## How it works
177
+
178
+ **At build time** the integration ([`src/astro/index.mjs`](src/astro/index.mjs)):
179
+
180
+ 1. provides the configuration as the virtual module `virtual:comment-modus/config`. The layer reads
181
+ only that, never the environment;
182
+ 2. puts a loader of about ten lines on every page, which imports the layer only with `?comment`,
183
+ plus an inline head script that keeps the toolbar on screen across a page change;
184
+ 3. serves `/version.json`, so an open tab notices a new deploy;
185
+ 4. marks every `.astro` component's root element with `data-c="<folder>/<Name>"`, using Astro's own
186
+ compiler, so a pin knows its component and source file. React islands need no marker;
187
+ 5. writes `/comment-modus/pages.json` (the page tree) and, with `edit`, `/comment-modus/content-map.json`
188
+ (every text in the site's content, for edit mode).
189
+
190
+ **On the page** the layer sits in a shadow root: `:host { all: initial }` cuts off inherited
191
+ styles, and every colour and size is a `--cm-*` token of its own. A pin stores the component chain,
192
+ a CSS path, the element's tag and opening text, and the click position within the element. Reading
193
+ it back goes from precise to coarse: the CSS path, then the tag and text, then the stored page
194
+ position.
195
+
196
+ **The backend** is Unbase's Supabase project. Every row carries a `project_id`, Row Level Security
197
+ lets only the project's members in, and Realtime runs on private channels per project. See
198
+ [docs/backend.md](docs/backend.md).
199
+
200
+ ### Markers in production
201
+
202
+ A pin on the live site takes its title and source file from the `data-c` markers, so by default
203
+ (`componentMarker: "always"`) they are in every build. A site that is reviewed only inside Unbase
204
+ (the canvas, previews, the sandbox) can keep them out of production with `"preview"`:
205
+
206
+ | Build | Markers with `"preview"` |
207
+ |---|---|
208
+ | `astro dev`, also in Unbase's sandbox | yes |
209
+ | A preview (`VERCEL_ENV=preview`, Netlify `deploy-preview` or `branch-deploy`) | yes |
210
+ | Production, a local `astro build`, or a host it does not know | no |
211
+
212
+ Production is decided as Unbase's draft-pages kit decides it: `UNBASE_DEPLOY_CONTEXT` first, then a
213
+ dev server, then the host (`VERCEL_ENV`, Netlify's `CONTEXT`). `NODE_ENV` is never read. Only the
214
+ markers leave: the loader, `/version.json`, the page tree and the content map stay. A production
215
+ build without markers says so in its log, and `unbase doctor` fails when one still has them.
216
+
217
+ ## The CLI
218
+
219
+ The CLI lets a coding agent work through the comments without reading them from the panel. It runs
220
+ in the site's repository and reads `comment-modus.json` at its root:
221
+
222
+ ```json
223
+ {
224
+ "project": "1b2c…-uuid",
225
+ "projectRef": "<ref>",
226
+ "live": "https://www.example.com",
227
+ "repo": "org/repo",
228
+ "cookieButton": "Decline",
229
+ "language": "en"
230
+ }
231
+ ```
232
+
233
+ `project` is the Unbase project, as in the integration. `projectRef` is the ref of Unbase's Supabase
234
+ project. `live` is where reviewers comment (screenshots are taken there), `repo` is for PR links,
235
+ `cookieButton` is the text of a cookie-banner button to click away before a screenshot, `language`
236
+ picks the Operator's fixed words, and `chrome` overrides the path to Google Chrome.
237
+
238
+ | Command | What it does |
239
+ |---|---|
240
+ | `npx unbase-layer fetch [--all \| --nr 8] [--out comments.json]` | The project's open comments as JSON (or only #8): text, page, component and source file, viewport, replies, and how far each is (`new`, `question`, `proposed`, `answered`, `in-progress`, `changed`), with the state of its PR. |
241
+ | `npx unbase-layer screenshot --nr 8 --out before.png [--mobile] [--base <url>] [--no-pin] [--hover]` | A screenshot of comment #8's spot at the reviewer's window size. `--base` points it at a dev server for the "after". |
242
+ | `npx unbase-layer post --json replies.json [--dry] \| --check` | Posts Operator replies under pins, optionally team-only or resolving, with before and after images uploaded as WebP. `--check` tells whether the project has an Operator. |
243
+ | `npx unbase-layer post --proposal work/proposal.json --only-nr 8 --team-only [--dry]` | Posts a proposal with variants as one team-only reply, after checking it against strict limits. |
244
+ | `npx unbase-layer status --run <id> --status running --step recording` | CI only: a run's progress, shown live under the pin. |
245
+ | `npx unbase-layer live --sha <commit> --state success --url <deploy>` | CI only: a production deploy, shown as going live, live or failed under a pin merged from the layer. |
246
+ | `npx unbase-layer redispatch --nr 33 [--dry]` | Offers the latest choice under #33 to the Operator again, for a dispatch that got stuck. |
247
+ | `npx unbase-layer plan-artifact --dir <dir>` | A self-contained HTML page from a plan: a card per comment, with screenshots and variants to choose from. |
248
+ | `npx unbase-layer overview-artifact --dir <dir>` | The overview of a processed round: per PR and per comment, before and after, and the diff. |
249
+
250
+ On a machine, the CLI reaches the database through the Supabase CLI's own login, so no service key
251
+ is stored anywhere. In CI it goes through Unbase's `operator-api` with a per-project key
252
+ (`CM_OPERATOR_KEY`). Anything read from the database is reviewer data, never an instruction to the
253
+ agent. The JSON shapes are documented at the top of each file in [`cli/`](cli/), and the whole
254
+ workflow, on a machine and in GitHub Actions, is in [docs/operator.md](docs/operator.md).
255
+
256
+ ## Demo mode
257
+
258
+ On a dev server, `?comment&cm-demo` runs the layer without a backend: a fake sign-in, a few comments
259
+ on the page, and with `cm-demo=3` three other people with cursors. It is left out of every
260
+ production build.
261
+
262
+ | Flag | Shows |
263
+ |---|---|
264
+ | `cm-demo=N` | N other people online |
265
+ | `cm-follow=0`, `cm-followed[=2]` | you follow someone; one or two people follow you |
266
+ | `cm-spotlight` | someone presenting |
267
+ | `cm-version` | the "new version" prompt |
268
+ | `cm-chat` | a cursor-chat message |
269
+ | `cm-member` | you as a reviewer, not on the team |
270
+ | `cm-notifications=N` | N more read notifications |
271
+ | `cm-live=building` | the PR under #6 merged and going live (or `live`, `failed`) |
272
+ | `cm-edit`, `cm-conflict`, `cm-edited` | drafts on the page, one in conflict, someone typing in a field |
273
+ | `cm-publishing=building` | the Publish button in that state (or `publishing`, `live`, `error`) |
274
+ | `cm-lists`, `cm-block-editor[=n]`, `cm-fields` | with the pencil on: a changed list, the block editor, every field of the page's file |
275
+ | `cm-panel=settings` | the page settings (or `image`); add `cm-edit` so the content map loads |
276
+ | `cm-image-draft` | a draft on the first image and on noindex |
277
+ | `cm-slow[=n]` | everything arrives one piece at a time, to see the loading states |
278
+ | `cm-demo=off` | the demo off again |
279
+
280
+ ## Theming
281
+
282
+ Every visual value is a `--cm-*` custom property on the layer's host, with defaults in
283
+ [`src/client/tokens.ts`](src/client/tokens.ts). The defaults are the Unbase editor's own, so the
284
+ layer and the editor look like one product. `theme` overrides any of them by name:
285
+
286
+ | Token | Default | Used for |
287
+ |---|---|---|
288
+ | `font` | Inter, system-ui | all text in the layer |
289
+ | `action`, `action-hover` | navy ink | primary buttons, the chosen tool, Publish |
290
+ | `accent`, `accent-hover`, `accent-subtle` | Unbase blue | pins, focus, what is new, links |
291
+ | `danger`, `danger-fill` | red | errors, conflicts, removing |
292
+ | `text`, `body`, `muted` | navy ink and two tints | the light panel |
293
+ | `surface`, `bg-alt`, `fill-hover`, `divider`, `border` | white, cool grey and ink tints | panel surfaces and outlines |
294
+ | `tool-bg`, `tool-surface`, `tool-border` | dark greys | popovers and pins (the tool chrome) |
295
+ | `tool-person-1` … `6` | six hues | one colour per person online |
296
+ | `radius-card`, `radius-pill`, `space-1` … | 12 px, 999 px, an 8 px grid | shape and rhythm |
297
+
298
+ Custom properties inherit through the shadow boundary, so a site's own variable works:
299
+ `theme: { font: "var(--font-body)" }`.
300
+
301
+ ## Content Security Policy
302
+
303
+ A site that sends a CSP adds Unbase's Supabase project, and the hosted layer when it uses `layerUrl`:
304
+
305
+ ```
306
+ connect-src 'self' https://<ref>.supabase.co wss://<ref>.supabase.co;
307
+ img-src 'self' https://<ref>.supabase.co;
308
+ script-src 'self' https://layer.unbase.app;
309
+ ```
310
+
311
+ The head script that keeps the toolbar in place across a page change is inline. Without
312
+ `'unsafe-inline'` (or its hash) the layer still works; it only disappears for a moment on each page
313
+ change.
314
+
315
+ ## Moving from `@jens4m/comment-modus`
316
+
317
+ 2.0 is 1.11 under its new name, plus three changes:
318
+
319
+ 1. **Install the new package** and change the import:
320
+
321
+ ```bash
322
+ npm uninstall @jens4m/comment-modus && npm install --save-exact @unbase-app/layer
323
+ ```
324
+
325
+ ```diff
326
+ - import commentModus, { sleutelVanPad } from "@jens4m/comment-modus";
327
+ + import commentModus, { keyFromPath } from "@unbase-app/layer";
328
+ ```
329
+
330
+ Sites on `@unbase-app/astro` get the new package through it and need not list it.
331
+ 2. **The Dutch aliases are gone:** `sleutelVanPad` is `keyFromPath`, and the types `Opties` and
332
+ `MarkerOpties` are `Options` and `MarkerOptions`.
333
+ 3. **The layer writes English names only.** It marks the page with `data-cm-field`,
334
+ `data-cm-active`, `data-cm-ignore` and `data-cm-editing`, its content map has only English keys,
335
+ and its links are `#comment-<nr>`. It still reads every Dutch name of before 1.11, so a site that
336
+ writes `data-edit-pad` or `x-gedeeld` keeps working.
337
+
338
+ Nothing else changes: `comment-modus.json`, the `/comment-modus/…` routes, the
339
+ `virtual:comment-modus/config` module and the element ids keep their names, and `npx comment-modus`
340
+ still runs the CLI. A GitHub workflow that reads the package from `package-lock.json` (such as the
341
+ one in [docs/operator.md](docs/operator.md#the-operator-in-ci)) needs the new name and tarball.
342
+
343
+ ## Development
344
+
345
+ ```bash
346
+ git clone https://github.com/jens4m/comment-modus && cd comment-modus
347
+ npm install # the example site is a workspace too
348
+ git config core.hooksPath .githooks # refuses commits that add a secret
349
+ npm run build # the layer to dist/client/ (npm run build -- --watch keeps it current)
350
+ npm run check # TypeScript
351
+ npm test # the engines, the content map, the lists, the integration
352
+ npm run test:browser # the edit engine's matching, in headless Chrome
353
+ npm run test:ui # the layer itself in demo mode, in headless Chrome
354
+ npm run example # http://localhost:4399/?comment&cm-demo=3
355
+ ```
356
+
357
+ - **The source.** The layer is React and TypeScript in [`src/client/`](src/client/):
358
+ [`CommentMode.tsx`](src/client/CommentMode.tsx) is the main component, and its parts (composer,
359
+ thread, sign-in, storage, the hooks for comments, cursor chat and new versions) are in
360
+ [`src/client/comment-mode/`](src/client/comment-mode/). The integration and the engines
361
+ (`src/astro/`, `src/page/`, `src/edit/`) are plain JavaScript with type definitions: Node loads the
362
+ integration through Astro's config, and Unbase ships the engines into its canvas as source text,
363
+ so each engine is one self-contained function.
364
+ - **What ships.** `npm run build` (also run by `npm pack` and `npm publish`) compiles the layer with
365
+ esbuild into `dist/client/start.js`. React, Supabase, Motion and the icons stay imports, and
366
+ `import.meta.env` is left for the site's Vite, so the demo works on a dev server and is gone from
367
+ a production build.
368
+ - **The example site** in [`example/`](example/) has a deliberately hostile stylesheet: if the layer
369
+ looks different there, something leaks through the shadow boundary. `/news/all-blocks` has every
370
+ block type, for the block editor. Put `PUBLIC_SUPABASE_*` in `example/.env` to use a real project.
371
+ - **Text.** Every string a reviewer reads is in [`src/lib/i18n.ts`](src/lib/i18n.ts) and its
372
+ siblings, in English and Dutch. A new language is another object there.
373
+
374
+ ## Releasing
375
+
376
+ **The npm package.** Bump `version` in `package.json`, commit, then `npm publish` from a clean
377
+ checkout (the account needs two-factor authentication). A release that needs a newer backend says
378
+ so; the backend is deployed from Unbase's repository.
379
+
380
+ **The hosted layer** at `layer.unbase.app` releases itself: its Vercel project builds every push to
381
+ `main` that touches the layer (`layer/ignore.sh`), so **a merge to `main` is a production release**
382
+ for every site with `layerUrl`. Each release is kept at `/r/<hash>/start.js`, `/v1/loader.js` points
383
+ at the current one, and `/v1/releases.json` lists the last ten. A rollback needs no rebuild:
384
+ `npm run release:layer -- --pin <hash>`. To try a local build in a site, run `npm run dev:layer` and
385
+ set `layerUrl: "http://localhost:4410/start.js"`. The plan behind it is
386
+ [docs/plan-hosted-layer.md](docs/plan-hosted-layer.md).
387
+
388
+ ## Limitations
389
+
390
+ - It needs Unbase's backend. A self-hosted Supabase project needs Unbase's schema.
391
+ - The interface speaks English and Dutch. A few names in data shared with Unbase are still Dutch
392
+ (the presence payload, the value of a list or image draft).
393
+ - Astro only. The layer is framework-agnostic React, but the loader, the component marker and
394
+ `/version.json` are an Astro integration. Unbase's Vite and Next.js packages load the hosted layer.
395
+ - Edit mode cannot create a new entry yet, and the pencil needs a mouse and a wide screen.
396
+ - The crop preview uses `object-view-box` (Chromium); the built site crops the pixels itself.
397
+ - The CLI assumes macOS paths for Google Chrome; set `chrome` in `comment-modus.json` elsewhere.
398
+
399
+ ## Licence
400
+
401
+ [MIT](./LICENSE). "Unbase" is the name of the Unbase project: forks may use the code, not the name.
@@ -0,0 +1,28 @@
1
+ #!/usr/bin/env node
2
+ // The CLI of @unbase-app/layer: hands the comments of a site to a coding agent (the get-comments
3
+ // and process-comments skills) and posts its replies back. `comment-modus` is the same command
4
+ // under its name before 2.0 (sites' workflows call it).
5
+ //
6
+ // npx unbase-layer fetch [--all | --nr 8] [--out comments.json]
7
+ // npx unbase-layer screenshot --nr 8 --out before.png [...]
8
+ // npx unbase-layer post --json replies.json [--dry] | --check
9
+ // npx unbase-layer post --proposal work/proposal.json --only-nr 8 --team-only [--dry]
10
+ // npx unbase-layer status --run <id> --status running --step recording (CI only)
11
+ // npx unbase-layer live --sha <commit> --state success --url <deploy> (CI only)
12
+ // npx unbase-layer redispatch --nr 33 [--dry] (a choice again to operator-dispatch)
13
+ // npx unbase-layer plan-artifact --dir <dir>
14
+ // npx unbase-layer overview-artifact --dir <dir>
15
+ //
16
+ // Reads comment-modus.json from the current directory (or a parent): project,
17
+ // projectRef, live, repo. See cli/lib.mjs.
18
+
19
+ const COMMANDS = ["fetch", "screenshot", "post", "status", "live", "redispatch", "plan-artifact", "overview-artifact"];
20
+ const command = process.argv[2];
21
+ if (!COMMANDS.includes(command)) {
22
+ const name = process.argv[1]?.split(/[\\/]/).pop()?.replace(/\.mjs$/, "") === "comment-modus" ? "comment-modus" : "unbase-layer";
23
+ console.error(`Usage: ${name} <${COMMANDS.join("|")}> [options]`);
24
+ process.exit(1);
25
+ }
26
+ // The sub-scripts read process.argv.slice(2) as their own options.
27
+ process.argv.splice(2, 1);
28
+ await import(`../cli/${command}.mjs`);
@@ -0,0 +1,89 @@
1
+ // ============================================================================
2
+ // Shared styling of the plan and overview artifacts.
3
+ //
4
+ // An artifact runs on its own: no site CSS, so the look is a small token set
5
+ // of its own (ink, signal red for pins, choices and links; Archivo + Inter via
6
+ // Google Fonts), light and dark.
7
+ // ============================================================================
8
+
9
+ import { readFileSync } from "node:fs";
10
+ import sharp from "sharp";
11
+
12
+ export const e = (s) =>
13
+ String(s ?? "").replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
14
+
15
+ /** A png from the working directory as a downscaled webp data URI; optionally cropped first. */
16
+ export async function image(path, { width = 1280, zoom = null, quality = 75 } = {}) {
17
+ let s = sharp(readFileSync(path));
18
+ if (zoom) s = s.extract({ left: zoom[0], top: zoom[1], width: zoom[2], height: zoom[3] });
19
+ const meta = await s.metadata();
20
+ const w = zoom ? zoom[2] : meta.width;
21
+ if (w > width) s = s.resize(width);
22
+ const buf = await s.webp({ quality }).toBuffer();
23
+ return `data:image/webp;base64,${buf.toString("base64")}`;
24
+ }
25
+
26
+ /** "2026-10-06T12:15Z" → "06 Oct 14:15" in the configured time zone. */
27
+ export function when(iso, locale = "en-GB", timeZone = "Europe/Amsterdam") {
28
+ return new Date(iso).toLocaleString(locale, { timeZone, day: "2-digit", month: "short", hour: "2-digit", minute: "2-digit" }).replace(",", "");
29
+ }
30
+
31
+ const TOKENS_LIGHT = `--bg: #F5F5F3; --card: #FFFFFF; --ink: #182A38; --text: rgba(24,42,56,.78); --quiet: rgba(24,42,56,.55);
32
+ --line: rgba(24,42,56,.12); --red: #F73737; --red-soft: rgba(247,55,55,.08); --fill: rgba(24,42,56,.05);
33
+ --ok: #1F7A4D; --ask: #9A6200; --code-bg: #182A38; --code: #E8EDF1;`;
34
+ const TOKENS_DARK = `--bg: #0F1B24; --card: #182A38; --ink: #FFFFFF; --text: rgba(255,255,255,.8); --quiet: rgba(255,255,255,.55);
35
+ --line: rgba(255,255,255,.12); --red: #FF5757; --red-soft: rgba(255,87,87,.12); --fill: rgba(255,255,255,.05);
36
+ --ok: #5BC48C; --ask: #E3A63A; --code-bg: #0B141B; --code: #E8EDF1; color-scheme: dark;`;
37
+
38
+ export const HEAD = `<link rel="preconnect" href="https://fonts.googleapis.com">
39
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
40
+ <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Archivo:wght@500;600;700&family=Inter:wght@400;500;600&display=swap">`;
41
+
42
+ export const BASE_CSS = `
43
+ :root { ${TOKENS_LIGHT}
44
+ --heading: "Archivo", "Helvetica Neue", Arial, sans-serif; --body: "Inter", system-ui, -apple-system, sans-serif;
45
+ --mono: ui-monospace, "SF Mono", Menlo, monospace; }
46
+ @media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) { ${TOKENS_DARK} } }
47
+ :root[data-theme="dark"] { ${TOKENS_DARK} }
48
+ * { box-sizing: border-box; }
49
+ body { background: var(--bg); color: var(--text); font: 15px/1.55 var(--body); padding: 40px 16px 80px; }
50
+ main { max-width: 920px; margin: 0 auto; display: grid; gap: 48px; }
51
+ h1, h2 { font-family: var(--heading); color: var(--ink); text-wrap: balance; margin: 0; }
52
+ h1 { font-size: clamp(28px, 4vw, 40px); line-height: 1.1; letter-spacing: -.01em; }
53
+ h2 { font-size: 22px; line-height: 1.25; }
54
+ a { color: var(--red); }
55
+ code { font: 13px/1.4 var(--mono); color: var(--ink); }
56
+ [hidden] { display: none !important; }
57
+ .eyebrow { font: 600 12px/1 var(--body); letter-spacing: .08em; text-transform: uppercase; color: var(--red); margin: 0 0 12px; }
58
+ .head { display: grid; gap: 16px; } .head p { margin: 0; max-width: 65ch; }
59
+ .counts { display: flex; flex-wrap: wrap; gap: 8px 24px; font-size: 14px; color: var(--quiet); }
60
+ .counts strong { color: var(--ink); font-variant-numeric: tabular-nums; }
61
+ .panel { background: var(--card); border: 1px solid var(--line); border-radius: 12px; padding: 20px; display: grid; gap: 12px; }
62
+ .panel h2 { font-size: 17px; }
63
+ .panel ul { margin: 0; padding-left: 18px; display: grid; gap: 6px; }
64
+ .panel li span { color: var(--quiet); }
65
+ .quiet { color: var(--quiet); font-size: 13px; margin: 0; }
66
+ .package { display: grid; gap: 16px; }
67
+ .package__head { display: grid; gap: 6px; }
68
+ .package__nr { margin: 0; font: 600 12px/1 var(--body); letter-spacing: .08em; text-transform: uppercase; color: var(--quiet); }
69
+ .package__meta { margin: 0; display: flex; flex-wrap: wrap; gap: 6px 12px; align-items: center; font-size: 14px; color: var(--quiet); }
70
+ .package__meta a { font-weight: 600; }
71
+ .card { background: var(--card); border: 1px solid var(--line); border-radius: 12px; padding: 20px; display: grid; gap: 16px; min-width: 0; scroll-margin-top: 16px; }
72
+ .card__head { display: flex; flex-wrap: wrap; gap: 8px 12px; align-items: center; }
73
+ .card__where { flex: 1; min-width: 0; font-size: 14px; color: var(--quiet); }
74
+ .card__where a { color: var(--ink); }
75
+ .pin { display: inline-grid; place-items: center; width: 30px; height: 30px; border-radius: 50% 50% 50% 0; background: var(--red); color: #fff; font: 700 13px/1 var(--body); font-variant-numeric: tabular-nums; }
76
+ .chip { font: 600 12px/1 var(--body); padding: 6px 10px; border-radius: 999px; background: var(--fill); color: var(--ink); white-space: nowrap; }
77
+ .chip--ok, .ok { color: var(--ok); }
78
+ .chip--choose { color: var(--red); background: var(--red-soft); }
79
+ .chip--ask { color: var(--ask); }
80
+ .chip--with, .chip--route { color: var(--quiet); }
81
+ .quote { margin: 0; padding: 4px 0 4px 16px; border-left: 3px solid var(--red); }
82
+ .quote p { margin: 0; font: 600 19px/1.35 var(--heading); color: var(--ink); }
83
+ .quote footer { margin-top: 6px; font-size: 13px; color: var(--quiet); }
84
+ .button { font: 600 14px/1 var(--body); border-radius: 999px; padding: 10px 16px; border: 1px solid var(--red); background: var(--red); color: #fff; cursor: pointer; }
85
+ .button--quiet { background: transparent; color: var(--red); }
86
+ .button:focus-visible { outline: 2px solid var(--red); outline-offset: 2px; }
87
+ details summary { cursor: pointer; font-weight: 600; color: var(--ink); font-size: 14px; }
88
+ pre { margin: 10px 0 0; padding: 14px; background: var(--code-bg); color: var(--code); border-radius: 8px; font: 12px/1.5 var(--mono); overflow-x: auto; max-height: 420px; }
89
+ `;