@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 +21 -0
- package/README.md +400 -2
- package/bin/unbase-layer.mjs +28 -0
- package/cli/artifact-style.mjs +89 -0
- package/cli/fetch.mjs +142 -0
- package/cli/lib.mjs +160 -0
- package/cli/live.mjs +35 -0
- package/cli/overview-artifact.mjs +142 -0
- package/cli/plan-artifact.mjs +337 -0
- package/cli/post.mjs +309 -0
- package/cli/redispatch.mjs +99 -0
- package/cli/screenshot.mjs +189 -0
- package/cli/status.mjs +50 -0
- package/cli/store.mjs +143 -0
- package/dist/client/start.d.ts +4 -0
- package/dist/client/start.js +12888 -0
- package/package.json +119 -4
- package/skills/build-comment/SKILL.md +61 -0
- package/skills/get-comments/SKILL.md +127 -0
- package/skills/process-comments/SKILL.md +115 -0
- package/skills/propose-comment/SKILL.md +79 -0
- package/src/astro/component-marker.mjs +161 -0
- package/src/astro/content-map-extra.mjs +192 -0
- package/src/astro/content-map.mjs +584 -0
- package/src/astro/deploy-context.mjs +66 -0
- package/src/astro/index.d.ts +97 -0
- package/src/astro/index.mjs +277 -0
- package/src/astro/pages.mjs +192 -0
- package/src/astro/version.mjs +13 -0
- package/src/edit/index.d.mts +178 -0
- package/src/edit/index.mjs +1002 -0
- package/src/page/index.d.mts +71 -0
- package/src/page/index.mjs +216 -0
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
|
-
|
|
1
|
+
<div align="center">
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
# @unbase-app/layer
|
|
4
|
+
|
|
5
|
+
**Review and edit an Astro site on the site itself. Add `?comment` to any address.**
|
|
6
|
+
|
|
7
|
+
[](https://www.npmjs.com/package/@unbase-app/layer)
|
|
8
|
+
[](./LICENSE)
|
|
9
|
+
[](#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) => ({ "&": "&", "<": "<", ">": ">", '"': """, "'": "'" })[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
|
+
`;
|