Connect the desktop app with one link and add tv links

developer-skills/pr-writing/SKILL.md

@@ -13,6 +13,8 @@ Explain the system change, not merely the changed files or "implements feature X
 
 Organize around the final behavior, architecture, validation, and important decisions. Neither the latest incremental edits nor the sequence of branch work describes the full result the reviewer must assess.
 
+Draft and ready PRs serve the same reader: someone assessing the change without the working conversation. Keep routine coordination in task records or conversation: approvals, review assignments, workflow transitions and pending process steps do not belong in the description. Leave out session details and agent names; when identifying an agent matters, say "an agent".
+
 ## Write for the visible diff
 
 Apply [cold-reader](../cold-reader/SKILL.md) and [plain-English](../plain-english-full/SKILL.md), including the cold-reader self-audit search before publishing.
@@ -21,7 +23,7 @@ Comparisons with the base are useful when both sides appear in the review: "remo
 
 Explain rationale positively: "Library X provides Y." Include it when a reviewer would plausibly wonder about the choice. Rationale that depends on discussing an alternative absent from the final diff belongs in design records or the relevant incremental commit, not the PR body.
 
-State what was actually validated and any material limits. Never imply an unperformed check passed.
+State what was actually validated and any material limits, explaining what the evidence establishes about the changed behavior. Include detail when it helps the reader assess confidence or investigate a relevant uncertainty, and retain any check record a spec explicitly requires. Never imply an unperformed check passed.
 
 ## Publish exact text
 

developer-skills/tvdev-contribute/SKILL.md

@@ -81,9 +81,9 @@ Several agents may run this skill in different worktrees on one host. Never link
 
 Once the work is complete, perform pre-merge docs prep as the docs spec defines it (`specs/spec-docs.md`, “Pre-merge docs prep”), before treating the contribution as ready to merge into a shared branch. Work-in-progress and draft PRs retain their working documents, including when presented for human spec review. Use that section's step 1 to decide which working documents to archive; add the archive preamble to each and move it to `docs/archive/YYYY-MM/`; delete the rest so `docs/working/` is empty. The archived files appear in the PR so the human sees what you judged worth keeping.
 
-Prepare the PR using [pr-writing](../pr-writing/SKILL.md).
+Prepare the PR using [pr-writing](../pr-writing/SKILL.md) and [cold-reader](../cold-reader/SKILL.md). A draft has the same purpose as a ready PR: explain the complete net change and useful verification evidence to a reader outside the working session. Keep routine approvals, review assignments, workflow transitions and pending process steps in task notes or conversation; deleting completed notes during docs prep does not require moving them into the PR. Omit session details and agent names (use "an agent" when needed), while retaining check records explicitly required by a spec.
 
-When presenting the PR, remind the human what their review must establish and make the relevant changes easy to find. Help them perform the minimum PR review defined by spec policy (`specs/spec-policy.md`, “Human PR review”): confirm that every spec delta is fully acceptable and scan the code and test footprint for unexpected scope or complexity. Specs are the product's core authority and slop-free zone; the human must understand and stand behind their changes under the spec ownership rules.
+In the conversation accompanying the PR, remind the human what their review must establish and make the relevant changes easy to find. Help them perform the minimum PR review defined by spec policy (`specs/spec-policy.md`, “Human PR review”): confirm that every spec delta is fully acceptable and scan the code and test footprint for unexpected scope or complexity. Specs are the product's core authority and slop-free zone; the human must understand and stand behind their changes under the spec ownership rules.
 
 Make red flags easy to assess: scope expansion, new dependencies, substantial new production or test-harness machinery, and edits to files or behaviors whose connection to the task is unclear. Explain why consequential changes belong and whether their cost is proportionate. This is an impact scan, not a requirement for the human to review every code or test line. Agents remain responsible for detailed correctness, coverage, and verification. Help the human inspect or test the result further when useful.
 

frames/app/setup.frame

@@ -0,0 +1,30 @@
+---
+title: Setup screen
+params:
+  appearance: { enum: [light, dark], default: light }
+  state: { enum: [ready, connecting, connected, error], default: ready, description: "ready, connecting, connected, or error" }
+script: |
+  import { setupPrototype, showConnected } from "../lib/setup.ts";
+
+  // Staging's stand-in for how long a server takes to answer Connect.
+  const SIMULATED_CONNECT_MS = 1500;
+
+  let cleanup: (() => void) | undefined;
+  let connectTimer: ReturnType<typeof setTimeout> | undefined;
+  const wire = () => {
+    cleanup?.();
+    clearTimeout(connectTimer);
+    const screen = document.querySelector<HTMLElement>(".setup-screen");
+    if (!screen) return;
+    cleanup = setupPrototype(screen, {
+      onConnect: () => {
+        connectTimer = setTimeout(() => showConnected(screen), SIMULATED_CONNECT_MS);
+      },
+    });
+  };
+  wire();
+  window.addEventListener("frameset:rendered", wire);
+---
+<div data-staging-theme="clouds">
+  {% render '../../specs/ui/setup/setup', state: state %}
+</div>

frames/app/system-modals/browser/access-token.frame

@@ -0,0 +1,6 @@
+---
+title: Access token required
+params:
+  appearance: { enum: [light, dark], default: light }
+---
+{% render '../../../../specs/ui/app/system-modal/system-modal', state: 'unauthorized' %}

frames/app/system-modals/browser/cant-connect.frame

@@ -0,0 +1,6 @@
+---
+title: Can’t connect with server
+params:
+  appearance: { enum: [light, dark], default: light }
+---
+{% render '../../../../specs/ui/app/system-modal/system-modal', state: 'error', server_url: 'http://100.101.102.103:32848', seconds: 5 %}

frames/app/system-modals/connecting.frame

@@ -0,0 +1,6 @@
+---
+title: Connecting
+params:
+  appearance: { enum: [light, dark], default: light }
+---
+{% render '../../../specs/ui/app/system-modal/system-modal', state: 'connecting' %}

frames/app/system-modals/desktop/access-token.frame

@@ -0,0 +1,7 @@
+---
+title: Access token required
+description: "The server's interface inside the desktop app, before it has rendered: no address bar and no drag handle of its own."
+params:
+  appearance: { enum: [light, dark], default: light }
+---
+{% render '../../../../specs/ui/app/system-modal/system-modal', state: 'unauthorized', context: 'desktop', drag_strip: true %}

frames/app/system-modals/desktop/cant-connect.frame

@@ -0,0 +1,7 @@
+---
+title: Can’t connect with server
+description: "The server's interface inside the desktop app when its first connection fails."
+params:
+  appearance: { enum: [light, dark], default: light }
+---
+{% render '../../../../specs/ui/app/system-modal/system-modal', state: 'error', context: 'desktop', drag_strip: true, server_url: 'http://100.101.102.103:32848', seconds: 5 %}

frames/app/system-modals/disconnected.frame

@@ -0,0 +1,11 @@
+---
+title: Disconnected
+params:
+  appearance: { enum: [light, dark], default: light }
+  seconds: { type: number, minimum: 0, multipleOf: 1, default: 5, description: "seconds until the next reconnection attempt; 0 shows Reconnecting now" }
+---
+{% if seconds > 0 %}
+{% render '../../../specs/ui/app/system-modal/system-modal', state: 'disconnected', seconds: seconds %}
+{% else %}
+{% render '../../../specs/ui/app/system-modal/system-modal', state: 'disconnected' %}
+{% endif %}

frames/app/system-modals/local/access-token.frame

@@ -0,0 +1,8 @@
+---
+title: Access token required
+description: "The desktop app's local page when the server rejects the saved connection's token."
+params:
+  appearance: { enum: [light, dark], default: light }
+  theme: { enum: [clouds], default: clouds }
+---
+{% render '../../../../specs/ui/app/system-modal/system-modal', state: 'unauthorized', context: 'local', drag_strip: true %}

frames/app/system-modals/local/cant-connect.frame

@@ -0,0 +1,8 @@
+---
+title: Can’t connect with server
+description: "The desktop app's local page when the saved connection's server cannot be reached."
+params:
+  appearance: { enum: [light, dark], default: light }
+  theme: { enum: [clouds], default: clouds }
+---
+{% render '../../../../specs/ui/app/system-modal/system-modal', state: 'error', context: 'local', drag_strip: true, server_url: 'http://100.101.102.103:32848', seconds: 5 %}

frames/app/system-modals/local/connecting.frame

@@ -0,0 +1,8 @@
+---
+title: Connecting
+description: "The desktop app's local page, starting a saved connection. It wears Clouds whatever theme the server uses."
+params:
+  appearance: { enum: [light, dark], default: light }
+  theme: { enum: [clouds], default: clouds }
+---
+{% render '../../../../specs/ui/app/system-modal/system-modal', state: 'connecting', context: 'local', drag_strip: true %}

frames/lib/setup.ts

@@ -0,0 +1,96 @@
+// Workshop wiring for the setup screen ([[specs/ui/setup/index.md]], Interaction):
+// Copy, and Connect's hand-off to the host. Staging only; it binds nothing. At
+// rest the markup matches the spec frame's render for the resulting state.
+
+// The copy button's confirmation dwell, stated in its spec's prose
+// ([[specs/ui/app/copy-button/index.md]], Testing); no data file carries it.
+const COPY_CONFIRM_MS = 1400;
+
+export interface SetupWiringOptions {
+  /** Connect submitted a non-empty link; the screen is already connecting. */
+  onConnect?: () => void;
+}
+
+const writeClipboard = (text: string): void => {
+  if (navigator.clipboard) {
+    void navigator.clipboard.writeText(text).catch(() => {});
+    return;
+  }
+  // Plain HTTP has no clipboard API; copy a selected textarea within the press.
+  const textarea = document.createElement("textarea");
+  textarea.value = text;
+  textarea.setAttribute("readonly", "");
+  textarea.style.position = "fixed";
+  textarea.style.opacity = "0";
+  document.body.append(textarea);
+  textarea.select();
+  try {
+    document.execCommand("copy");
+  } catch {
+    // Copying is best-effort in the workshop.
+  }
+  textarea.remove();
+};
+
+/** Pose the connected state on a wired screen, as its render would. */
+export const showConnected = (screen: HTMLElement): void => {
+  const setupDocument = screen.querySelector<HTMLElement>(".setup-document");
+  if (setupDocument) setupDocument.inert = true;
+  screen.querySelector(".setup-done")?.removeAttribute("aria-hidden");
+  screen.dataset.state = "connected";
+};
+
+/** Wire one rendered setup screen. Returns a disposer. */
+export const setupPrototype = (screen: HTMLElement, options: SetupWiringOptions = {}): (() => void) => {
+  const copyButton = screen.querySelector<HTMLButtonElement>(".setup-prompt .copy-button");
+  const form = screen.querySelector<HTMLFormElement>(".setup-link");
+  if (!copyButton || !form) {
+    throw new Error("The setup screen needs its copy button and its link form");
+  }
+  const status = copyButton.nextElementSibling as HTMLElement | null;
+  const field = form.querySelector<HTMLInputElement>("input");
+  const submit = form.querySelector<HTMLButtonElement>(".setup-submit");
+  const confirmation = copyButton.querySelector(".copy-button-done")?.textContent?.trim() ?? "";
+  let confirmTimer: ReturnType<typeof setTimeout> | undefined;
+
+  const onCopy = (): void => {
+    writeClipboard(copyButton.getAttribute("prompt") ?? "");
+    copyButton.toggleAttribute("copied", true);
+    if (status) status.textContent = confirmation;
+    clearTimeout(confirmTimer);
+    confirmTimer = setTimeout(() => {
+      copyButton.toggleAttribute("copied", false);
+      if (status) status.textContent = "";
+    }, COPY_CONFIRM_MS);
+  };
+
+  const onSubmit = (event: Event): void => {
+    event.preventDefault();
+    if (screen.dataset.state !== "ready" && screen.dataset.state !== "error") return;
+    if (!field?.value.trim()) return;
+    // Connecting renders without the error treatment: the hint returns and
+    // the field is no longer invalid.
+    field.removeAttribute("aria-invalid");
+    field.removeAttribute("aria-describedby");
+    const error = screen.querySelector<HTMLElement>("#setup-link-error");
+    if (error) {
+      const hint = document.createElement("p");
+      hint.className = "setup-hint";
+      hint.innerHTML = 'The link looks like <code>http://…:32848/?token=…</code>';
+      error.replaceWith(hint);
+    }
+    screen.dataset.state = "connecting";
+    field.disabled = true;
+    if (submit) submit.disabled = true;
+    options.onConnect?.();
+  };
+
+  copyButton.addEventListener("click", onCopy);
+  form.addEventListener("submit", onSubmit);
+
+  return () => {
+    clearTimeout(confirmTimer);
+    copyButton.removeEventListener("click", onCopy);
+    form.removeEventListener("submit", onSubmit);
+  };
+};

frameset.json

@@ -1,7 +1,7 @@
 {
   "root": ".",
   "imports": {
-    "specs/ui/{app,foundation}/**/*.frame": [
+    "specs/ui/{app,foundation,setup}/**/*.frame": [
       "specs/ui/foundation/index.css",
       "specs/ui/foundation/tokens/app.css",
       "frames/lib/foundation.ts"
@@ -35,6 +35,11 @@
           "path": "frames/app/app.frame",
           "title": "App"
         },
+        {
+          "type": "frame",
+          "path": "frames/app/setup.frame",
+          "title": "Setup screen"
+        },
         {
           "type": "folder",
           "title": "Onboarding",
@@ -155,14 +160,78 @@
           "title": "Copy button"
         },
         {
-          "type": "frame",
-          "path": "frames/app/system-modal.frame",
-          "title": "System modal"
-        },
-        {
-          "type": "frame",
-          "path": "frames/app/upgrade-gate.frame",
-          "title": "Upgrade gate"
+          "type": "folder",
+          "title": "System modals",
+          "children": [
+            {
+              "type": "frame",
+              "path": "frames/app/system-modals/connecting.frame",
+              "title": "Connecting"
+            },
+            {
+              "type": "frame",
+              "path": "frames/app/system-modals/disconnected.frame",
+              "title": "Disconnected"
+            },
+            {
+              "type": "folder",
+              "title": "Browser",
+              "children": [
+                {
+                  "type": "frame",
+                  "path": "frames/app/system-modals/browser/access-token.frame",
+                  "title": "Access token required"
+                },
+                {
+                  "type": "frame",
+                  "path": "frames/app/system-modals/browser/cant-connect.frame",
+                  "title": "Can\u2019t connect with server"
+                }
+              ]
+            },
+            {
+              "type": "folder",
+              "title": "Desktop",
+              "children": [
+                {
+                  "type": "frame",
+                  "path": "frames/app/system-modals/desktop/access-token.frame",
+                  "title": "Access token required"
+                },
+                {
+                  "type": "frame",
+                  "path": "frames/app/system-modals/desktop/cant-connect.frame",
+                  "title": "Can\u2019t connect with server"
+                }
+              ]
+            },
+            {
+              "type": "folder",
+              "title": "Desktop local page",
+              "children": [
+                {
+                  "type": "frame",
+                  "path": "frames/app/system-modals/local/connecting.frame",
+                  "title": "Connecting"
+                },
+                {
+                  "type": "frame",
+                  "path": "frames/app/system-modals/local/access-token.frame",
+                  "title": "Access token required"
+                },
+                {
+                  "type": "frame",
+                  "path": "frames/app/system-modals/local/cant-connect.frame",
+                  "title": "Can\u2019t connect with server"
+                }
+              ]
+            },
+            {
+              "type": "frame",
+              "path": "frames/app/upgrade-gate.frame",
+              "title": "Upgrade gate"
+            }
+          ]
         },
         {
           "type": "frame",

packages/canonical/styles/canonical/v2/elements/button/styles.css

@@ -212,6 +212,16 @@
   padding: var(--space-2);
 }
 
+:where(button[size="lg"]) {
+  font-size: var(--text-lg);
+  line-height: var(--line-control-lg);
+  padding: var(--space-8) var(--space-20);
+}
+
+:where(button[size="lg"][icon]) {
+  padding: var(--space-8);
+}
+
 /* A sized control sizes the icon it holds: whatever size the composer put on
    the icon, the control's own wins — `tv-icon[size]` names a fixed pixel
    size, so left alone the icon would ignore the control shrinking around it.

packages/canonical/styles/canonical/v2/elements/input/styles.css

@@ -34,6 +34,15 @@
   resize: vertical;
 }
 
+/* The large size matches a large button beside the field
+   ([[ui/foundation/button/button.css]]): the same text step, line and
+   vertical padding step, so the two are the same height. */
+:where(:is(input:not([type]), input[type=""], input[type="text"], input[type="email"], input[type="url"], input[type="tel"], input[type="password"], input[type="number"], textarea)[data-size="lg"]) {
+  font-size: var(--text-lg);
+  line-height: var(--line-control-lg);
+  padding: var(--space-8) var(--space-12);
+}
+
 /* Shared error-message styling; validation and announcement belong to the surface. */
 :where(.tv-error) {
   margin: 0;