@telepath-computer/television 0.1.216 → 1.3.3

package/dist/skills/television/SKILL.md

@@ -10,6 +10,8 @@ Television is a persistent artifact channel for agents.
 
 Load this skill when you need to create, update, inspect, focus, delete, or otherwise manage Television channels and artifacts.
 
+Read the [theming guidance](./theming.md) when creating, revising, or bringing an installed theme up to date.
+
 Re-read this skill only if it is not already in your context or you know it changed.
 
 ## When to use Television
@@ -133,7 +135,7 @@ tv help <command>
 
 Commands group into four intents:
 
-- **Channel and display commands** — create, inspect, remove, or switch channels, or change the active display theme (`create-channel`, `list-channels`, `get-channel`, `remove-channel`, `focus-channel`, `focus-status`, `set-theme`).
+- **Channel and display commands** — create, inspect, rename, remove, or switch channels, or change the active display theme (`create-channel`, `list-channels`, `get-channel`, `update-channel`, `remove-channel`, `focus-channel`, `focus-status`, `set-theme`).
 - **Artifact creation commands** — register path or URL artifacts (`create-path-artifact`, `create-url-artifact`).
 - **Artifact management commands** — inspect, retitle, repoint, focus, list, or delete existing artifacts (`delete-artifact`, `get-artifact`, `list-artifacts`, `update-artifact`, `focus-artifact`).
 - **Server and environment commands** — operate on the Television server itself (`serve`, `status`, `stop`, `storage-path`, `telemetry`, `skills install`).
@@ -148,7 +150,15 @@ Starting, installing, upgrading, or reconfiguring the server — `tv serve` flag
 
 ## Read vs mutate
 
-Read commands print JSON. Workflow commands print plain text. Most mutation commands also print plain text, but `tv set-theme` is intentionally silent on success. `tv serve` startup output is human-readable connection text.
+Read commands print JSON. Workflow commands and most mutation commands print plain text. On success, `tv set-theme` prints one of these forms:
+
+```text
+Active theme changed from '<previous>' to '<new>'.
+Active theme unchanged: '<selection>'.
+Active theme: '<new>'.
+```
+
+The first two forms are available when the opening selection read succeeds. The third confirms activation when that read is unavailable. Theme labels preserve exact installed theme IDs and use `None` for no theme. `tv serve` startup output is human-readable connection text.
 
 Use read commands when you need authoritative state for planning or verification. Use mutation commands when you are intentionally changing Television state.
 
@@ -379,12 +389,16 @@ A directory artifact needs root `index.html` or `index.htm`. Keep sibling assets
 <script type="module" src="./main.js"></script>
 ```
 
-Use `/canonical/v1/styles.css` for Television's canonical artifact stylesheet:
+Use Television's canonical artifact stylesheet and record the app version whose canonical surface you authored against:
 
 ```html
-<link rel="stylesheet" href="/canonical/v1/styles.css" />
+<link rel="stylesheet" href="/canonical/v2/styles.css?authoredForAppVersion=<version>" />
 ```
 
+Replace `<version>` with the target Television app version. For a running server, read the exact release `version` from `tv status`; when working in a Television checkout, read the exact version from the checkout root `package.json`. Copy that exact release version unchanged into `authoredForAppVersion`. A missing version or the `0.0.0` development sentinel does not identify a release, so omit the metadata.
+
+`authoredForAppVersion` is advisory authoring context for a future agent. The server ignores it when serving the stylesheet, so it neither asserts compatibility nor controls whether the artifact loads. Set it when creating an artifact or deliberately re-authoring one against that app surface. Preserve an existing `authoredForAppVersion` value during unrelated maintenance. If you cannot establish the target app version, omit the query parameter; the canonical URL remains valid without it.
+
 ### Suggested HTML file set
 
 For durable HTML artifacts, write nearby documentation so a future agent can maintain the work:
@@ -483,21 +497,25 @@ If the browser placeholder for an ordinary non-Television URL is not sufficient,
 # HTML artifact style
 
 Write a complete HTML document for the Television viewer. Load both canonical
-v1 resources in the document head:
+v2 resources in the document head:
 
 ```html
-<link rel="stylesheet" href="/canonical/v1/styles.css">
-<script type="module" src="/canonical/v1/components.js"></script>
+<link rel="stylesheet" href="/canonical/v2/styles.css?authoredForAppVersion=<version>">
+<script type="module" src="/canonical/v2/components.js"></script>
 ```
 
+Replace `<version>` with the Television app version whose canonical surface you
+are authoring against. The Artifact workflow section explains how to find that
+version and when to set, preserve, or omit this advisory query parameter.
+
 The stylesheet provides Television's reset, Hind font, public design tokens,
-semantic document defaults, and published element styles. The script registers
-the published custom elements. Add local CSS for the artifact's own layout,
+semantic document defaults, and public element styles. The script registers
+the public custom elements. Add local CSS for the artifact's own layout,
 density, hierarchy, and specialized presentation.
 
-Lean on semantic HTML first. Headings, paragraphs, lists, links, code blocks,
-blockquotes, rules, images, and tables receive readable document styling from
-the canonical sheet. Rely on those defaults instead of recreating baseline
+Lean on semantic HTML first. Put `text-display="prose"` on a body or section
+to apply readable styling to its headings, paragraphs, lists, links, code
+blocks, blockquotes, rules, images and tables. Rely on those defaults instead of recreating baseline
 typography in each artifact.
 
 ## Page header
@@ -515,8 +533,7 @@ Use a `<header>` containing an `<h1>` and, when useful, one `<p>` subtitle:
 </header>
 ```
 
-A lead paragraph in a header is automatically muted and drawn close to its
-heading.
+Use the prose region for document reading rhythm; author any special header treatment locally.
 
 For prose-like documents, 32px padding on the top and sides with 64px at the
 bottom is a useful starting point. Adapt it to the document's content and
@@ -544,66 +561,104 @@ fallback when the artifact should remain readable without the canonical sheet:
 Fallbacks are paired: a guarded ground goes with a guarded text color, using
 values that read together.
 
-This published inventory is closed. Do not invent token names; when no public
+This public inventory is closed. Do not invent token names; when no public
 token expresses a value, use an intentional literal, and when one does, use the
 documented token with a literal fallback where appropriate.
 
-### Color values and ramps
-
-- Base: `--black`, `--white`.
-- Neutral: `--neutral-50`, `--neutral-100`, `--neutral-200`,
-  `--neutral-300`, `--neutral-400`, `--neutral-500`, `--neutral-600`,
-  `--neutral-700`, `--neutral-800`, `--neutral-900`, `--neutral-950`.
-- Alpha: `--alpha-50`, `--alpha-100`, `--alpha-200`, `--alpha-300`,
-  `--alpha-400`, `--alpha-500`, `--alpha-600`, `--alpha-700`,
-  `--alpha-800`, `--alpha-900`, `--alpha-950`.
-- Blue: `--blue-50`, `--blue-100`, `--blue-200`, `--blue-300`,
-  `--blue-400`, `--blue-500`, `--blue-600`, `--blue-700`, `--blue-800`,
-  `--blue-900`.
-- Red: `--red-50`, `--red-100`, `--red-200`, `--red-300`, `--red-400`,
-  `--red-500`, `--red-600`, `--red-700`, `--red-800`, `--red-900`.
-- Yellow: `--yellow-50`, `--yellow-100`, `--yellow-200`, `--yellow-300`,
-  `--yellow-400`, `--yellow-500`, `--yellow-600`, `--yellow-700`,
-  `--yellow-800`, `--yellow-900`, `--yellow-950`.
-- Green: `--green-50`, `--green-100`, `--green-200`, `--green-300`,
-  `--green-400`, `--green-500`, `--green-600`, `--green-700`,
-  `--green-800`, `--green-900`.
-- Orange: `--orange-50`, `--orange-100`, `--orange-200`, `--orange-300`,
-  `--orange-400`, `--orange-500`, `--orange-600`, `--orange-700`,
-  `--orange-800`, `--orange-900`.
-- Purple: `--purple-50`, `--purple-100`, `--purple-200`, `--purple-300`,
-  `--purple-400`, `--purple-500`, `--purple-600`, `--purple-700`,
-  `--purple-800`, `--purple-900`.
-- Current-color tints: `--tint-50`, `--tint-100`, `--tint-200`,
-  `--tint-300`, `--tint-400`, `--tint-500`, `--tint-600`, `--tint-700`,
-  `--tint-800`, `--tint-900`, `--tint-950`.
-
-Prefer the semantic roles when they express the intended meaning:
-`--color-text`, `--color-text-muted`, `--color-primary`,
-`--color-on-primary`, `--color-selected`, `--color-link`, `--color-danger`,
-`--color-success`, `--color-warning`, `--color-background`, `--color-surface`,
-`--color-surface-muted`, `--color-border`, and `--color-border-muted`.
+### Fonts
+
+`--font-sans`, `--font-mono`, `--font-weight-normal`, `--font-weight-medium`, `--font-weight-semibold`.
+
+### Colors
+
+`--checkbox-color`, `--panel-background`, `--panel-text-color`, `--panel-border-color`, `--panel-border`, `--panel-edge-highlight`, `--panel-edge-shadow`, `--option-background-highlighted`, `--option-background-active`, `--control-background`, `--control-text-color`, `--control-border-color`, `--control-border-width`, `--control-border`, `--input-placeholder-text-color`, `--neutral`, `--red`, `--orange`, `--yellow`, `--green`, `--cyan`, `--blue`, `--purple`, `--pink`, `--accent`, `--neutral-50`, `--neutral-100`, `--neutral-200`, `--neutral-300`, `--neutral-400`, `--neutral-500`, `--neutral-600`, `--neutral-700`, `--neutral-800`, `--neutral-900`, `--neutral-950`, `--red-50`, `--red-100`, `--red-200`, `--red-300`, `--red-400`, `--red-500`, `--red-600`, `--red-700`, `--red-800`, `--red-900`, `--red-950`, `--orange-50`, `--orange-100`, `--orange-200`, `--orange-300`, `--orange-400`, `--orange-500`, `--orange-600`, `--orange-700`, `--orange-800`, `--orange-900`, `--orange-950`, `--yellow-50`, `--yellow-100`, `--yellow-200`, `--yellow-300`, `--yellow-400`, `--yellow-500`, `--yellow-600`, `--yellow-700`, `--yellow-800`, `--yellow-900`, `--yellow-950`, `--green-50`, `--green-100`, `--green-200`, `--green-300`, `--green-400`, `--green-500`, `--green-600`, `--green-700`, `--green-800`, `--green-900`, `--green-950`, `--cyan-50`, `--cyan-100`, `--cyan-200`, `--cyan-300`, `--cyan-400`, `--cyan-500`, `--cyan-600`, `--cyan-700`, `--cyan-800`, `--cyan-900`, `--cyan-950`, `--blue-50`, `--blue-100`, `--blue-200`, `--blue-300`, `--blue-400`, `--blue-500`, `--blue-600`, `--blue-700`, `--blue-800`, `--blue-900`, `--blue-950`, `--purple-50`, `--purple-100`, `--purple-200`, `--purple-300`, `--purple-400`, `--purple-500`, `--purple-600`, `--purple-700`, `--purple-800`, `--purple-900`, `--purple-950`, `--pink-50`, `--pink-100`, `--pink-200`, `--pink-300`, `--pink-400`, `--pink-500`, `--pink-600`, `--pink-700`, `--pink-800`, `--pink-900`, `--pink-950`, `--accent-50`, `--accent-100`, `--accent-200`, `--accent-300`, `--accent-400`, `--accent-500`, `--accent-600`, `--accent-700`, `--accent-800`, `--accent-900`, `--accent-950`, `--neutral-alpha-5`, `--neutral-alpha-10`, `--neutral-alpha-15`, `--neutral-alpha-25`, `--neutral-alpha-50`, `--neutral-alpha-75`, `--red-alpha-5`, `--red-alpha-10`, `--red-alpha-15`, `--red-alpha-25`, `--red-alpha-50`, `--red-alpha-75`, `--orange-alpha-5`, `--orange-alpha-10`, `--orange-alpha-15`, `--orange-alpha-25`, `--orange-alpha-50`, `--orange-alpha-75`, `--yellow-alpha-5`, `--yellow-alpha-10`, `--yellow-alpha-15`, `--yellow-alpha-25`, `--yellow-alpha-50`, `--yellow-alpha-75`, `--green-alpha-5`, `--green-alpha-10`, `--green-alpha-15`, `--green-alpha-25`, `--green-alpha-50`, `--green-alpha-75`, `--cyan-alpha-5`, `--cyan-alpha-10`, `--cyan-alpha-15`, `--cyan-alpha-25`, `--cyan-alpha-50`, `--cyan-alpha-75`, `--blue-alpha-5`, `--blue-alpha-10`, `--blue-alpha-15`, `--blue-alpha-25`, `--blue-alpha-50`, `--blue-alpha-75`, `--purple-alpha-5`, `--purple-alpha-10`, `--purple-alpha-15`, `--purple-alpha-25`, `--purple-alpha-50`, `--purple-alpha-75`, `--pink-alpha-5`, `--pink-alpha-10`, `--pink-alpha-15`, `--pink-alpha-25`, `--pink-alpha-50`, `--pink-alpha-75`, `--accent-alpha-5`, `--accent-alpha-10`, `--accent-alpha-15`, `--accent-alpha-25`, `--accent-alpha-50`, `--accent-alpha-75`, `--alpha-3`, `--alpha-5`, `--alpha-10`, `--alpha-15`, `--alpha-20`, `--alpha-25`, `--alpha-40`, `--alpha-50`, `--alpha-75`, `--hover-mix`, `--alpha-active`, `--tint-hover`, `--tint-active`, `--icon-check`, `--color-surface`, `--color-surface-muted`, `--color-text`, `--color-text-muted`, `--color-text-reversed`, `--color-border`, `--color-danger`, `--tint-danger`, `--tint-danger-hover`, `--tint-danger-active`, `--color-alert`, `--tint-alert`, `--tint-alert-hover`, `--tint-alert-active`, `--color-success`, `--tint-success`, `--tint-surface`, `--tint-surface-muted`, `--color-primary`, `--tint-primary`, `--tint-primary-hover`, `--tint-primary-active`, `--color-primary-text`, `--outline-focus`, `--control-background-hover`, `--control-background-active`, `--color-primary-hover`, `--color-primary-active`, `--color-danger-hover`, `--color-danger-active`, `--color-alert-hover`, `--color-alert-active`, `--color-link`, `--color-overlay`, `--state-flip`, `--contrast-flip`.
 
 ### Type
 
-- Scale and line height: `--text-base`, `--text-sm`, `--text-md`,
-  `--text-lg`, `--text-xl`, `--text-2xl`, `--text-3xl`, `--text-4xl`,
-  `--text-scale`, `--leading-base`.
-- Families: `--font-sans`, `--font-mono`.
-- Weights: `--font-weight-normal`, `--font-weight-medium`,
-  `--font-weight-body`, `--font-weight-semibold`.
+`--control-font-size`, `--text-base`, `--text-sm`, `--text-md`, `--text-lg`, `--text-xl`, `--text-2xl`, `--text-3xl`, `--text-4xl`, `--line-control`, `--line-control-sm`.
+
+### Spacing and radii
 
-### Spacing, radii, and elevation
+`--control-radius`, `--control-padding`, `--space-2`, `--space-3`, `--space-4`, `--space-6`, `--space-8`, `--space-10`, `--space-12`, `--space-16`, `--space-20`, `--space-24`, `--space-32`, `--space-48`, `--space-64`, `--radius-pill`, `--panel-radius`, `--popover-distance`.
 
-- Spacing: `--space-2`, `--space-4`, `--space-6`, `--space-8`,
-  `--space-10`, `--space-12`, `--space-16`, `--space-20`, `--space-24`,
-  `--space-32`, `--space-48`, `--space-64`.
-- Radii: `--radius-4`, `--radius-6`, `--radius-8`, `--radius-12`,
-  `--radius-16`, `--radius-24`, `--radius-full`.
-- Floating-panel elevation: `--shadow-panel`.
+### Shadows
+
+`--shadow-sm`, `--shadow-md`, `--shadow-lg`, `--shadow-xl`, `--popover-shadow`, `--dialog-shadow`.
+
+### Layers
+
+`--layer-ground`, `--layer-panel`, `--layer-overlay`.
 
 ## Canonical components
 
+### Native inputs and errors
+
+Native text-entry inputs and textareas receive shared styling automatically.
+Supported input types are absent or empty type, `text`, `email`, `url`, `tel`,
+`password` and `number`; search fields and other controls are outside this
+treatment. Give each field an accessible label; a placeholder is only a hint.
+Use `disabled` to disable a field and `readonly` to retain selectable contents
+without editing. Preserve the keyboard focus ring and state styling.
+
+When presenting a validation error, set `aria-invalid="true"` and associate
+the message using `aria-describedby`. The foundation supplies the invalid
+border. Use a paragraph with `class="tv-error"` for shared message styling:
+
+```html
+<label for="name">Name</label>
+<input id="name" aria-invalid="true" aria-describedby="name-error">
+<p id="name-error" class="tv-error">Enter a name.</p>
+```
+
+Explain what needs correcting in text, not color alone. Preserve existing hint
+IDs when adding the error ID to `aria-describedby`. When the error clears,
+remove `aria-invalid` (or set it to `false`), remove only the error ID from
+`aria-describedby`, and remove the message or hide it with native `hidden`.
+Do not mark untouched required fields invalid merely because they are empty.
+
+`tv-error` adds no validation, visibility, focus or announcement behavior and
+can also style messages outside inputs. Decide whether an asynchronous error
+needs a live announcement; the class does not imply `role="alert"`.
+
+### Popovers, menus and selects
+
+Pair a panel with the ID of a trigger button in the same document:
+
+```html
+<button id="details">Details</button>
+<tv-popover trigger="details" open>Panel contents</tv-popover>
+<button id="manual-details">Manual details</button>
+<tv-popover trigger="manual-details" manual>Explicitly dismissed contents</tv-popover>
+
+<button id="actions">Actions</button>
+<tv-menu trigger="actions" open>
+  <tv-menu-item>Rename</tv-menu-item>
+  <hr>
+  <tv-menu-item intent="danger">Delete</tv-menu-item>
+</tv-menu>
+<button id="manual-actions">Manual actions</button>
+<tv-menu trigger="manual-actions" manual>…</tv-menu>
+
+<button id="choice" aria-label="Appearance"></button>
+<tv-select trigger="choice" open>
+  <tv-option value="light" selected>Light</tv-option>
+  <tv-option value="dark">Dark</tv-option>
+</tv-select>
+```
+
+The `open` attribute controls visibility; omit it for the usual closed initial state.
+Popover and menu triggers toggle their panels. Manual popovers and menus require
+explicit closing. Ordinary panels dismiss on outside press or Escape; menus
+also close on item activation and support keyboard navigation and typeahead.
+Author action handlers on the menu items.
+
+Menus and popovers prefer below the trigger with left edges aligned, flip toward
+more room when needed, and constrain scrolling within their own document. Selects
+open over the selected row and keep an owning Settings-style popover open. A select
+copies its selected option label to the trigger. Its `value` property reads or sets
+a matching option value; a committed user choice emits `change`. No direction
+attributes or internal classes are part of the authoring API.
+
 ### Static checkbox lists
 
 Use `checkbox-list` and `checkbox-item` for a checklist whose state is authored
@@ -619,11 +674,11 @@ into the document:
 `checked` marks a completed `checkbox-item`. Checked rows render muted and
 struck through, and the marker shows a not-allowed cursor to communicate its
 static nature. The list is presentational and does not toggle when pressed.
-`--checkbox-color` is the checkbox item's documented styling property:
+The shared `--checkbox-color` token controls checked marker fill and border:
 
 ```css
-checkbox-item {
-  --checkbox-color: var(--green-600);
+:root {
+  --checkbox-color: var(--color-success);
 }
 ```
 
@@ -654,7 +709,7 @@ The public icon names are:
 - `phone`, `web`, `tag`, `bookmark`, `table`, `code`, `group`, `up`, `down`
 - `money`, `bank`, `card`, `wallet`, `gauge`, `activity`, `trend-up`
 - `trend-down`, `database`, `server`, `deploy`, `list`, `terminal`, `branch`
-- `shield`
+- `shield`, `select`
 
 Choose a name from this catalog. When the catalog has no suitable glyph, use a
 text label or an emoji.
@@ -666,3 +721,5 @@ artifact frame. Build responsive layouts from the document's available width
 and height. Vertical document scrolling is appropriate for overflow; reserve
 horizontal scrolling for content that needs width, such as a data table or
 timeline.
+
+For a native dialog, put its contents in one direct `.dialog-content` child: `<dialog><div class="dialog-content">…</div></dialog>`. Author content layout on that child. It scrolls within the viewport and any authored dialog height or maximum height while the dialog paints its rim and broad shadow. Unwrapped dialogs retain native overflow.