tux-review 0.1.0

package/README.md

@@ -0,0 +1,67 @@
+# TUX Review
+
+TUX turns a running web UI into a review artifact. Reviewers can attach
+structured, machine-readable feedback to pages, routes, components, element
+instances, and UI states directly in the browser.
+
+This is the **Node.js/npm variant** of TUX. It includes the `tux` CLI, a
+local review server, framework templates, and the framework-agnostic Review
+Client. It has no runtime dependencies and requires Node.js 20 or newer.
+
+Choose this package if your project uses npm/JavaScript or you need the
+`tux-review/client` JavaScript export. If you only want a stdlib-only CLI and
+server, install the separate but command-compatible Python package from PyPI
+instead. Do not install both for one project.
+
+## Install
+
+Run the CLI without a global installation:
+
+```bash
+npx --yes --package=tux-review tux --help
+```
+
+Or install it in the project (recommended):
+
+```bash
+npm install --save-dev tux-review
+npx tux --version
+```
+
+## Typical workflow
+
+After installation, run every CLI command through `npx tux …` (or `tux …` if
+you installed it globally). For a clickable design:
+
+```bash
+npx tux design install --framework vanilla
+npx tux design create --framework vanilla --name checkout
+npx tux design start-review
+```
+
+For an existing application, use the live-review workflow:
+
+```bash
+npx tux live install
+npx tux live start-review --url http://localhost:3000
+```
+
+Feedback is stored in `.tux/feedback.json` by default and can be inspected or
+exported with `tux feedback show` and `tux feedback export`.
+
+## What is included
+
+- A deterministic CLI for design and live UI reviews
+- A plain-JavaScript browser Review Client (`tux-review/client`)
+- Vanilla, React, Vue, and Angular design templates
+- Canonical JSON feedback and agent skills
+
+## Documentation and support
+
+The complete guide, examples, and normative specification are in the
+[GitHub repository](https://github.com/sommelo1/tux). Report issues at
+[github.com/sommelo1/tux/issues](https://github.com/sommelo1/tux/issues).
+
+## License
+
+[MIT](https://github.com/sommelo1/tux/blob/main/LICENSE)

package/bin/tux.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/** Entry point for the `tux` binary. */
+import { run } from '../src/cli.js';
+
+const isTTY = process.stdin.isTTY ?? false;
+const result = await run(process.argv.slice(2), { isTTY });
+if (result.stdout) process.stdout.write(result.stdout);
+if (result.stderr) process.stderr.write(result.stderr);
+if (result.keepAlive) {
+  // keep the process alive while a foreground server runs
+  process.on('SIGINT', () => {
+    result.keepAlive.close();
+    process.exit(0);
+  });
+} else {
+  process.exitCode = result.exit;
+}

package/client/tux-review.css

@@ -0,0 +1,155 @@
+/* TUX Review Client styles — tux-owned classes only; host element
+ * selectors are never touched (Application Isolation, SPC section 61).
+ * Themeable via --tux-* tokens; values reference host variables, so host
+ * values win. Tokens live on :root because tux surfaces render in three
+ * places: the overlay (#tux-root), the top-layer dialog (portaled editor,
+ * markers, reparented float/sidebar/toast), and — for the hover outline —
+ * directly on host elements. */
+
+:root {
+  --tux-primary: var(--primary, #569cd6);
+  --tux-surface: var(--card-bg, #fff);
+  --tux-surface2: var(--chip-bg, #f0f2f5);
+  --tux-border: var(--card-border, rgba(0, 0, 0, .12));
+  --tux-text: var(--on-surface, #1e1e1e);
+  --tux-muted: var(--outline, #6e6e6e);
+  --tux-danger: #c62828;
+  --tux-rec: #e53935;
+  --tux-green: #2e7d32;
+  --tux-yellow: #f9a825;
+  --tux-radius: 12px;
+  --tux-shadow: 0 4px 16px rgba(0, 0, 0, .16);
+}
+
+#tux-root {
+  font-family: system-ui, sans-serif;
+  font-size: 14px;
+  color: var(--tux-text);
+}
+
+/* Floating activation surface (launcher + state label). While a native
+   <dialog> is open, the client reparents this element into the dialog so
+   it stays clickable above the backdrop. */
+#tux-root .tux-float,
+dialog[open] .tux-float {
+  position: fixed; right: 14px; bottom: 14px; z-index: 2147483000;
+  display: flex; align-items: center; gap: 10px;
+  font-family: system-ui, sans-serif;
+  font-size: 14px;
+  color: var(--tux-text);
+}
+
+/* Launcher: light gray when off, recording red (pulsing) when commenting. */
+.tux-float .tux-launcher {
+  width: 44px; height: 44px; border-radius: 50%;
+  border: 1px solid var(--tux-border); cursor: pointer;
+  background: var(--tux-surface2); color: var(--tux-muted);
+  font-size: 20px; box-shadow: var(--tux-shadow);
+}
+.tux-float .tux-launcher.tux-active {
+  background: var(--tux-rec); color: #fff; border-color: var(--tux-rec);
+  animation: tux-rec-pulse 1.6s ease-out infinite;
+}
+.tux-float .tux-launcher.tux-invite {
+  animation: tux-invite-pulse 2s ease-in-out infinite;
+}
+@keyframes tux-rec-pulse {
+  0% { box-shadow: 0 0 0 0 rgba(229, 57, 53, .45), var(--tux-shadow); }
+  70% { box-shadow: 0 0 0 14px rgba(229, 57, 53, 0), var(--tux-shadow); }
+  100% { box-shadow: 0 0 0 0 rgba(229, 57, 53, 0), var(--tux-shadow); }
+}
+@keyframes tux-invite-pulse {
+  0%, 100% { box-shadow: 0 0 0 0 rgba(86, 156, 214, .40), var(--tux-shadow); }
+  50% { box-shadow: 0 0 0 12px rgba(86, 156, 214, 0), var(--tux-shadow); }
+}
+
+/* Persistent state label next to the launcher. */
+.tux-float .tux-launcher-hint {
+  height: 44px; display: flex; align-items: center;
+  padding: 0 14px; border-radius: 999px;
+  background: var(--tux-surface); border: 1px solid var(--tux-border);
+  box-shadow: var(--tux-shadow); color: var(--tux-text);
+  font-size: 12.5px; font-weight: 600; white-space: nowrap;
+}
+.tux-float .tux-launcher-hint::before {
+  content: ""; width: 8px; height: 8px; border-radius: 50%;
+  background: var(--tux-muted); margin-right: 8px; flex: none;
+}
+.tux-float .tux-launcher-hint.tux-hint-on::before { background: var(--tux-rec); }
+.tux-float .tux-launcher-hint.tux-hint-invite::before {
+  background: var(--tux-primary);
+  animation: tux-invite-pulse 2s ease-in-out infinite;
+}
+
+body.tux-mode * { cursor: crosshair !important; }
+
+#tux-root .tux-layer { position: absolute; left: 0; top: 0; }
+
+/* Hover outline — lands on host elements, so this rule is intentionally
+   unscoped: the class name is tux-owned and the outline must work both on
+   plain page elements and inside top-layer dialogs. .tux-editing marks the
+   target of the currently open editor with the same outline. */
+.tux-hover, .tux-editing { outline: 2px dashed var(--tux-primary) !important; outline-offset: -2px; }
+
+/* Markers and the editor portal into native dialogs when the target lives
+   in the top layer — the dialog[open] alternative keeps them styled there. */
+:is(#tux-root, dialog[open]) .tux-marker {
+  position: absolute; z-index: 2147483001;
+  min-width: 22px; height: 22px; padding: 0 4px; border-radius: 11px;
+  border: 2px solid var(--tux-surface); background: var(--tux-yellow);
+  color: #000; font-size: 11px; font-weight: 700; cursor: pointer;
+  box-shadow: var(--tux-shadow);
+}
+:is(#tux-root, dialog[open]) .tux-marker.tux-resolved { background: var(--tux-green); color: #fff; }
+
+:is(#tux-root, dialog[open]) .tux-editor {
+  display: none; position: absolute; z-index: 2147483002;
+  width: 300px; padding: 12px; border-radius: var(--tux-radius);
+  border: 1px solid var(--tux-border); background: var(--tux-surface);
+  box-shadow: var(--tux-shadow); text-align: left;
+}
+:is(#tux-root, dialog[open]) .tux-editor.tux-open { display: block; }
+:is(#tux-root, dialog[open]) .tux-ed-head { display: flex; justify-content: space-between; font-size: 12px; color: var(--tux-muted); margin-bottom: 6px; }
+:is(#tux-root, dialog[open]) .tux-ed-target { font-size: 11px; color: var(--tux-muted); background: var(--tux-surface2); border-radius: 8px; padding: 6px 8px; margin-bottom: 8px; word-break: break-all; }
+:is(#tux-root, dialog[open]) .tux-ed-row { display: flex; gap: 8px; align-items: center; font-size: 12px; margin-bottom: 8px; color: var(--tux-muted); }
+:is(#tux-root, dialog[open]) .tux-editor select, :is(#tux-root, dialog[open]) .tux-editor textarea {
+  font: inherit; color: var(--tux-text); background: var(--tux-surface);
+  border: 1px solid var(--tux-border); border-radius: 8px; padding: 6px 8px;
+}
+:is(#tux-root, dialog[open]) .tux-editor textarea { width: 100%; min-height: 70px; box-sizing: border-box; resize: vertical; }
+:is(#tux-root, dialog[open]) .tux-ed-actions { display: flex; gap: 8px; justify-content: flex-end; margin-top: 8px; }
+:is(#tux-root, dialog[open]) .tux-btn-primary { background: var(--tux-primary); color: #fff; border: none; border-radius: 999px; padding: 6px 14px; cursor: pointer; }
+:is(#tux-root, dialog[open]) .tux-btn-ghost { background: none; border: 1px solid var(--tux-border); color: var(--tux-muted); border-radius: 999px; padding: 6px 14px; cursor: pointer; }
+:is(#tux-root, dialog[open]) .tux-btn-danger { background: none; border: 1px solid var(--tux-danger); color: var(--tux-danger); border-radius: 999px; padding: 6px 14px; cursor: pointer; }
+:is(#tux-root, dialog[open]) .tux-x { background: none; border: none; color: var(--tux-muted); cursor: pointer; }
+
+/* Sidebar and toast can be reparented into an open dialog together with
+   the float — the dialog[open] alternative keeps them styled there. */
+:is(#tux-root, dialog[open]) .tux-sidebar {
+  position: fixed; right: 0; top: 0; bottom: 0; z-index: 2147482999;
+  width: 300px; background: var(--tux-surface); border-left: 1px solid var(--tux-border);
+  box-shadow: var(--tux-shadow); transform: translateX(100%); transition: transform .18s ease;
+  display: flex; flex-direction: column;
+}
+:is(#tux-root, dialog[open]) .tux-sidebar.tux-open { transform: translateX(0); }
+:is(#tux-root, dialog[open]) .tux-sb-head { display: flex; justify-content: space-between; align-items: center; padding: 12px 14px; font-weight: 600; border-bottom: 1px solid var(--tux-border); }
+:is(#tux-root, dialog[open]) .tux-sb-close { background: none; border: none; color: var(--tux-muted); cursor: pointer; }
+:is(#tux-root, dialog[open]) .tux-sb-meta { padding: 8px 14px; font-size: 11px; color: var(--tux-muted); border-bottom: 1px solid var(--tux-border); }
+:is(#tux-root, dialog[open]) .tux-sb-list { overflow: auto; flex: 1; padding: 8px; }
+:is(#tux-root, dialog[open]) .tux-sb-item { display: grid; grid-template-columns: auto 1fr; gap: 2px 8px; padding: 8px; border-radius: 10px; background: var(--tux-surface2); margin-bottom: 8px; cursor: pointer; }
+:is(#tux-root, dialog[open]) .tux-sb-item.tux-done { opacity: .55; }
+:is(#tux-root, dialog[open]) .tux-sb-type { grid-row: span 2; align-self: center; font-size: 10px; text-transform: uppercase; padding: 3px 7px; border-radius: 999px; background: var(--tux-yellow); }
+:is(#tux-root, dialog[open]) .tux-type-approval { background: var(--tux-green); color: #fff; }
+:is(#tux-root, dialog[open]) .tux-type-question { background: var(--tux-primary); color: #fff; }
+:is(#tux-root, dialog[open]) .tux-type-issue { background: var(--tux-danger); color: #fff; }
+:is(#tux-root, dialog[open]) .tux-sb-text { font-size: 12px; line-height: 1.4; word-break: break-word; }
+:is(#tux-root, dialog[open]) .tux-sb-route { font-size: 10px; color: var(--tux-muted); }
+:is(#tux-root, dialog[open]) .tux-sb-empty { color: var(--tux-muted); font-size: 12px; padding: 12px; }
+
+:is(#tux-root, dialog[open]) .tux-toast {
+  position: fixed; left: 50%; bottom: 20px; transform: translateX(-50%) translateY(20px);
+  z-index: 2147483003; background: var(--tux-text); color: var(--tux-surface);
+  padding: 8px 16px; border-radius: 999px; font-size: 12px; opacity: 0;
+  transition: opacity .15s ease, transform .15s ease; pointer-events: none;
+}
+:is(#tux-root, dialog[open]) .tux-toast.tux-visible { opacity: 1; transform: translateX(-50%) translateY(0); }