@jantcz/webai 0.0.0-stage → 0.2.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.
Files changed (49) hide show
  1. package/LICENSE +135 -0
  2. package/README.md +24 -2
  3. package/agents/.claude-plugin/plugin.json +4 -0
  4. package/agents/README.md +17 -0
  5. package/agents/agents/a11y-reviewer.md +16 -0
  6. package/agents/agents/copy-editor.md +14 -0
  7. package/agents/skills/czech-copy/SKILL.md +18 -0
  8. package/agents/skills/element-edit/SKILL.md +51 -0
  9. package/agents/skills/stock-images/SKILL.md +25 -0
  10. package/agents/skills/verify-change/SKILL.md +19 -0
  11. package/agents/skills/web-styling/SKILL.md +20 -0
  12. package/bin/webai-agent.js +355 -0
  13. package/bin/webai-bridge.js +5 -0
  14. package/bin/webai.js +4 -0
  15. package/package.json +85 -4
  16. package/src/agents/claude.js +161 -0
  17. package/src/agents/codex.js +111 -0
  18. package/src/agents/custom.js +64 -0
  19. package/src/agents/docker.js +46 -0
  20. package/src/agents/gemini.js +102 -0
  21. package/src/agents/index.js +25 -0
  22. package/src/agents/opencode.js +117 -0
  23. package/src/agents/pack.js +99 -0
  24. package/src/agents/pi.js +143 -0
  25. package/src/agents/webai.js +66 -0
  26. package/src/astro/annotate.js +163 -0
  27. package/src/astro/index.d.ts +5 -0
  28. package/src/astro/index.js +40 -0
  29. package/src/bridge.js +62 -0
  30. package/src/cli.js +108 -0
  31. package/src/client/overlay.js +887 -0
  32. package/src/config.js +23 -0
  33. package/src/core.js +102 -0
  34. package/src/history.js +108 -0
  35. package/src/html.js +43 -0
  36. package/src/index.d.ts +228 -0
  37. package/src/index.js +10 -0
  38. package/src/inject.js +80 -0
  39. package/src/next/index.d.ts +8 -0
  40. package/src/next/index.js +59 -0
  41. package/src/next/script.d.ts +3 -0
  42. package/src/next/script.js +13 -0
  43. package/src/prompt.js +17 -0
  44. package/src/proxy.js +68 -0
  45. package/src/server.js +211 -0
  46. package/src/session.js +455 -0
  47. package/src/static.js +64 -0
  48. package/src/vite.d.ts +5 -0
  49. package/src/vite.js +42 -0
package/LICENSE ADDED
@@ -0,0 +1,135 @@
1
+ Required Notice: Copyright (c) 2026 Jan Truhlar (https://github.com/JanTcz/WebAI)
2
+
3
+ Free for noncommercial use. Commercial use needs a commercial license, see COMMERCIAL.md (https://github.com/JanTcz/WebAI/blob/main/COMMERCIAL.md).
4
+
5
+ # PolyForm Noncommercial License 1.0.0
6
+
7
+ <https://polyformproject.org/licenses/noncommercial/1.0.0>
8
+
9
+ ## Acceptance
10
+
11
+ In order to get any license under these terms, you must agree
12
+ to them as both strict obligations and conditions to all
13
+ your licenses.
14
+
15
+ ## Copyright License
16
+
17
+ The licensor grants you a copyright license for the
18
+ software to do everything you might do with the software
19
+ that would otherwise infringe the licensor's copyright
20
+ in it for any permitted purpose. However, you may
21
+ only distribute the software according to [Distribution
22
+ License](#distribution-license) and make changes or new works
23
+ based on the software according to [Changes and New Works
24
+ License](#changes-and-new-works-license).
25
+
26
+ ## Distribution License
27
+
28
+ The licensor grants you an additional copyright license
29
+ to distribute copies of the software. Your license
30
+ to distribute covers distributing the software with
31
+ changes and new works permitted by [Changes and New Works
32
+ License](#changes-and-new-works-license).
33
+
34
+ ## Notices
35
+
36
+ You must ensure that anyone who gets a copy of any part of
37
+ the software from you also gets a copy of these terms or the
38
+ URL for them above, as well as copies of any plain-text lines
39
+ beginning with `Required Notice:` that the licensor provided
40
+ with the software. For example:
41
+
42
+ > Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
43
+
44
+ ## Changes and New Works License
45
+
46
+ The licensor grants you an additional copyright license to
47
+ make changes and new works based on the software for any
48
+ permitted purpose.
49
+
50
+ ## Patent License
51
+
52
+ The licensor grants you a patent license for the software that
53
+ covers patent claims the licensor can license, or becomes able
54
+ to license, that you would infringe by using the software.
55
+
56
+ ## Noncommercial Purposes
57
+
58
+ Any noncommercial purpose is a permitted purpose.
59
+
60
+ ## Personal Uses
61
+
62
+ Personal use for research, experiment, and testing for
63
+ the benefit of public knowledge, personal study, private
64
+ entertainment, hobby projects, amateur pursuits, or religious
65
+ observance, without any anticipated commercial application,
66
+ is use for a permitted purpose.
67
+
68
+ ## Noncommercial Organizations
69
+
70
+ Use by any charitable organization, educational institution,
71
+ public research organization, public safety or health
72
+ organization, environmental protection organization,
73
+ or government institution is use for a permitted purpose
74
+ regardless of the source of funding or obligations resulting
75
+ from the funding.
76
+
77
+ ## Fair Use
78
+
79
+ You may have "fair use" rights for the software under the
80
+ law. These terms do not limit them.
81
+
82
+ ## No Other Rights
83
+
84
+ These terms do not allow you to sublicense or transfer any of
85
+ your licenses to anyone else, or prevent the licensor from
86
+ granting licenses to anyone else. These terms do not imply
87
+ any other licenses.
88
+
89
+ ## Patent Defense
90
+
91
+ If you make any written claim that the software infringes or
92
+ contributes to infringement of any patent, your patent license
93
+ for the software granted under these terms ends immediately. If
94
+ your company makes such a claim, your patent license ends
95
+ immediately for work on behalf of your company.
96
+
97
+ ## Violations
98
+
99
+ The first time you are notified in writing that you have
100
+ violated any of these terms, or done anything with the software
101
+ not covered by your licenses, your licenses can nonetheless
102
+ continue if you come into full compliance with these terms,
103
+ and take practical steps to correct past violations, within
104
+ 32 days of receiving notice. Otherwise, all your licenses
105
+ end immediately.
106
+
107
+ ## No Liability
108
+
109
+ ***As far as the law allows, the software comes as is, without
110
+ any warranty or condition, and the licensor will not be liable
111
+ to you for any damages arising out of these terms or the use
112
+ or nature of the software, under any kind of legal claim.***
113
+
114
+ ## Definitions
115
+
116
+ The **licensor** is the individual or entity offering these
117
+ terms, and the **software** is the software the licensor makes
118
+ available under these terms.
119
+
120
+ **You** refers to the individual or entity agreeing to these
121
+ terms.
122
+
123
+ **Your company** is any legal entity, sole proprietorship,
124
+ or other kind of organization that you work for, plus all
125
+ organizations that have control over, are under the control of,
126
+ or are under common control with that organization. **Control**
127
+ means ownership of substantially all the assets of an entity,
128
+ or the power to direct its management and policies by vote,
129
+ contract, or otherwise. Control can be direct or indirect.
130
+
131
+ **Your licenses** are all the licenses granted to you for the
132
+ software under these terms.
133
+
134
+ **Use** means anything you do with the software requiring one
135
+ of your licenses.
package/README.md CHANGED
@@ -1,3 +1,25 @@
1
- # Temporary Holding Version
1
+ # @jantcz/webai
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
+ [![Socket Badge](https://socket.dev/api/badge/npm/package/@jantcz/webai)](https://socket.dev/npm/package/@jantcz/webai)
4
+
5
+ Shift+click any element on your site, say what to change, and an AI coding
6
+ agent edits the source: Claude Code, Codex, Gemini CLI, OpenCode, Pi, your own
7
+ command, or a built-in agent with free models. Development only: nothing ends
8
+ up in your build.
9
+
10
+ ```bash
11
+ npx @jantcz/webai ./site # a folder of HTML files
12
+ npx @jantcz/webai --target http://localhost:3000 # in front of any running dev server
13
+ ```
14
+
15
+ ```js
16
+ import webai from '@jantcz/webai/vite'; // vite.config: plugins: [webai()]
17
+ import webai from '@jantcz/webai/astro'; // astro.config: integrations: [webai()]
18
+ import { withWebai } from '@jantcz/webai/next'; // next.config: export default withWebai(config)
19
+ import { createWebai } from '@jantcz/webai'; // any Node server: app.use(createWebai().middleware)
20
+ ```
21
+
22
+ No install at all: the [WebAI Editor](https://jantcz.github.io/WebAI/editor/)
23
+ edits any website in the browser.
24
+
25
+ Documentation, examples and Docker: https://github.com/JanTcz/WebAI
@@ -0,0 +1,4 @@
1
+ {
2
+ "name": "webai",
3
+ "description": "Skills and subagents for editing a website from the webai browser overlay."
4
+ }
@@ -0,0 +1,17 @@
1
+ # Agents and skills for webai
2
+
3
+ A single source for all CLIs. Skills use the Agent Skills standard
4
+ (`skills/<name>/SKILL.md` with `name` and `description` frontmatter); subagents
5
+ are Markdown files with frontmatter (`agents/<name>.md`).
6
+
7
+ | CLI | How it picks them up |
8
+ |---|---|
9
+ | Claude Code | `--plugin-dir` pointing at this folder, names `webai:<skill>` |
10
+ | Codex | symlinks in `<project>/.agents/skills/`, subagents generated into `.codex/agents/*.toml` |
11
+ | Gemini CLI | symlinks in `<project>/.agents/skills/` and `<project>/.gemini/agents/` |
12
+
13
+ The overlay creates the symlinks the first time a given agent is used and never
14
+ overwrites an existing file of the same name.
15
+
16
+ Subagents have no `tools` field: tool names differ between CLIs, so the
17
+ read-only restriction lives in the instruction text.
@@ -0,0 +1,16 @@
1
+ ---
2
+ name: a11y-reviewer
3
+ description: Read-only accessibility review of recently changed Astro/HTML/CSS files - heading order, alt texts, link and button names, color contrast, focus visibility. Use after a visual or structural change when the user asks for a check, or for larger edits.
4
+ ---
5
+
6
+ You are an accessibility reviewer. **Do not edit anything**; only read files and report findings.
7
+
8
+ In the changed files, check:
9
+ - heading order (no skipped levels, one `h1` per page),
10
+ - `alt` on images (decorative ones `alt=""`), names for buttons and links without text (`aria-label`),
11
+ - text contrast against the background based on CSS variables (AA: 4.5 : 1, large text 3 : 1),
12
+ - visible focus (`:focus-visible`) and that interactive elements are `a`/`button`, not `div`,
13
+ - `lang` and meaningful link text.
14
+
15
+ Output: a list of findings `file:line – problem – suggested fix`, sorted by
16
+ severity. If everything is fine, say so in one sentence.
@@ -0,0 +1,14 @@
1
+ ---
2
+ name: copy-editor
3
+ description: Read-only copy review of text changed on the website - typography (quotes, non-breaking spaces, dashes), grammar, tone consistency, CTA wording. Follows the czech-copy skill for Czech sites. Use when the user asks to proofread or after larger text edits.
4
+ ---
5
+
6
+ You are a proofreader of website copy. **Do not edit anything**; only read and suggest.
7
+
8
+ Work in the language of the site (check `lang` and the surrounding text). For
9
+ Czech, follow the rules of the `czech-copy` skill (quotes „“, non-breaking
10
+ spaces after k s v z o u a i, dashes, numbers, `s.r.o.`); for other languages,
11
+ apply that language's standard typography. Also watch grammar, agreement,
12
+ consistent form of address and the length of `meta description`.
13
+
14
+ Output: a list of `file:line – original → suggested – why`. If there are no findings, one sentence.
@@ -0,0 +1,18 @@
1
+ ---
2
+ name: czech-copy
3
+ description: Use when writing or editing Czech text on a web page (headings, buttons, paragraphs, meta descriptions). Czech typography rules - quotes, non-breaking spaces after one-letter words, dashes, numbers, abbreviations.
4
+ ---
5
+
6
+ # Czech text on the web
7
+
8
+ - Quotes „like this“ (low 99, high 66), nested ‚like this‘.
9
+ - Non-breaking space (`&nbsp;` in HTML/Astro, U+00A0 in data) after the one-letter
10
+ words **k s v z o u a i** and between a number and its unit (`10&nbsp;%`, `5&nbsp;kB`).
11
+ - Dash with spaces – like this (en dash); ranges without spaces: 9–17 h.
12
+ - Thousands separated by a non-breaking space: 12&nbsp;500 Kč.
13
+ - `s.r.o.` always with periods, likewise `a.s.`.
14
+ - Buttons and links: a verb in the imperative or a clear target („Napište nám“,
15
+ „Ceník služeb“), not „Klikněte zde“ ("click here").
16
+ - Keep `meta description` between 120 and 160 characters. No period at the end of headings.
17
+ - Keep the tone of the surrounding text (formal "vy" address, sentence length). If the
18
+ project has content tests (lengths, card counts), respect them.
@@ -0,0 +1,51 @@
1
+ ---
2
+ name: element-edit
3
+ description: Use when a request comes from the webai overlay with a [Selected element] block (selector, text, html, and a source file:line:col when the framework provides one). Explains how to find where the element's content and styles really live and how to make a minimal, safe edit.
4
+ ---
5
+
6
+ # Editing an element selected in the overlay
7
+
8
+ The message starts with a `[Selected element]` block: the CSS selector, the
9
+ element's text and an HTML excerpt. With Astro and static HTML it also has
10
+ `source: <file>:LINE:COLUMN`, the location of the element's opening tag.
11
+
12
+ ## Finding the element
13
+
14
+ 1. **With `source:`** open that file at that line. `inside:` lists the files
15
+ the component is nested in (parents), which helps when the props passed in
16
+ need to change.
17
+ 2. **Without `source:`** (React, Vue, Svelte, Next.js, server templates) search
18
+ the sources for the most specific piece first: a distinctive phrase of the
19
+ text, then class names from the selector or the HTML, then the component
20
+ structure around it. Ignore build output. If several places match, pick the
21
+ one whose surrounding markup matches the HTML excerpt.
22
+
23
+ ## Where the content really lives
24
+
25
+ **The text is often not in the template.** When the element renders an
26
+ expression (`{…}` in Astro/JSX/Svelte, `{{ … }}` in Vue and most server
27
+ templates), find the source:
28
+ - props → where the component is used (`inside:` or grep for the component name),
29
+ - the same file's script part (Astro frontmatter `---`, `<script setup>`, top of a JSX module),
30
+ - content and data folders (`src/content/**`, Markdown with frontmatter, `src/data/**`,
31
+ `src/config/**`, `src/i18n/**`, JSON/YAML, a CMS export).
32
+ Edit the data source, not the template, otherwise the change drifts from the other places.
33
+
34
+ ## Making the change
35
+
36
+ 1. **Component used more than once.** A template change shows up everywhere the
37
+ component is used. Grep for its name. If the user clearly wants the change in
38
+ one place only, add a prop or variant instead of changing it for all, and
39
+ mention it in your answer.
40
+ 2. **Styles.** First the component's own styles (Astro/Vue/Svelte `<style>`,
41
+ CSS modules next to it), then the project's global CSS or Tailwind classes,
42
+ whatever the project already uses. See the `web-styling` skill.
43
+ 3. `data-webai-src`, `data-astro-cid-*` and framework-generated class names in
44
+ the HTML are dev server artifacts. Never write them into source files.
45
+ 4. Do not edit build output or dependencies: `dist/`, `build/`, `.next/`,
46
+ `.astro/`, `node_modules/`.
47
+
48
+ ## When the request is unclear
49
+
50
+ For changes that alter the page structure, ask briefly (one question) instead of guessing.
51
+ For small things (text, color, spacing), make the most likely choice and say what you chose.
@@ -0,0 +1,25 @@
1
+ ---
2
+ name: stock-images
3
+ description: Use when the user asks for a photo, illustration or other image that the project doesn't have yet. Covers finding openly licensed images on Openverse, saving them into the project, alt text and the credit line their licenses require.
4
+ ---
5
+
6
+ # Free images with the right credit
7
+
8
+ - **Search Openverse** (no key needed), only images that may be used on a
9
+ commercial site and resized or cropped:
10
+ `https://api.openverse.org/v1/images/?q=<a few English words>&license_type=commercial,modification&mature=false&page_size=8`.
11
+ Each result has `title`, `creator`, `license`, `license_version`, `width`,
12
+ `height`, `url` (the file) and `foreign_landing_url` (its page). You can't
13
+ see the images: pick by title and size, and prefer landscape images at least
14
+ 1200 px wide for wide spots.
15
+ - **Save it into the project**, don't hotlink: where the project keeps images
16
+ (`src/assets/` with `astro:assets`' `<Image>`, or `public/images/`). If you
17
+ have no tool to download a binary file, tell the user the URL and the path to
18
+ save it to, and write the markup for that path.
19
+ - **Alt text** says what the image shows in this page's context, not the file
20
+ name. Purely decorative images get `alt=""`.
21
+ - **Credit:** licenses other than CC0 and Public Domain Mark (`cc0`, `pdm`)
22
+ require one. Put it right under the image or in the footer:
23
+ `Photo: <a href="{foreign_landing_url}">{title}</a> by {creator}, CC {LICENSE} {version}`.
24
+ Never drop or shorten it when restyling.
25
+ - Say in your answer which image you chose, from where and under which license.
@@ -0,0 +1,19 @@
1
+ ---
2
+ name: verify-change
3
+ description: Use after editing source files from the webai overlay, before answering. How to check the change without starting servers, and how to report what was and was not verified.
4
+ ---
5
+
6
+ # Verifying a change
7
+
8
+ The dev server is running and reloads the change on its own. **Do not run**
9
+ `npm run dev`, `astro dev`, `vite`, `next dev` or a build.
10
+
11
+ 1. Re-read the edited section: the template's syntax (closed tags, `{}`
12
+ expressions, Astro frontmatter between `---`, JSX attribute names).
13
+ 2. If you have shell access and the project has a quick check (`npm run check`,
14
+ `astro check`, `tsc`, lint), run it only for edits that could break types or
15
+ imports. Skip it for text or color changes.
16
+ 3. The shell is often disabled in the overlay. If you cannot run a check, do not
17
+ work around it. Say in your answer what you did not verify.
18
+ 4. Answer: one or two sentences on what changed and where (`file:line`), plus
19
+ anything left unverified or affecting other parts of the site.
@@ -0,0 +1,20 @@
1
+ ---
2
+ name: web-styling
3
+ description: Use when changing colors, spacing, typography, layout or responsiveness of a web page element. Covers reusing design tokens, keeping WCAG AA contrast, responsive breakpoints and avoiding specificity hacks.
4
+ ---
5
+
6
+ # Styling without breaking the site
7
+
8
+ - **Tokens, not values.** Before writing a color, size or spacing, look for
9
+ custom properties (`grep -n -- '--' src/styles` / `:root`). Use an existing token;
10
+ add a new one only when none fits, and name it by purpose, not by color.
11
+ - **WCAG AA contrast:** body text ≥ 4.5 : 1, large text (≥ 24 px, or 18.66 px bold)
12
+ and icons ≥ 3 : 1. When you change a text or background color, compute the contrast and state it in your answer.
13
+ - **Responsiveness:** use the breakpoints the project already has (grep `@media`). Do not introduce new
14
+ values. Think the change through for mobile too.
15
+ - **Specificity:** no `!important` and no ID selectors to win overrides. Prefer editing
16
+ the original rule. In a scoped Astro `<style>`, styles apply only to that component;
17
+ reaching children of other components needs `:global()`.
18
+ - **Motion:** wrap animations in `@media (prefers-reduced-motion: no-preference)`.
19
+ - **Hiding content:** `display: none` on content is often a mistake. Make sure the user really wants
20
+ to hide the element, not just move it.