npm - @telepath-computer/television - Versions diffs - 0.1.27 → 0.1.29 - Mend

@telepath-computer/television 0.1.27 → 0.1.29

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 (14) hide show

package/README.md +21 -10
package/dist/browser/assets/index-Bi8GHwko.js +548 -0
package/dist/browser/assets/index-BporpGDZ.css +1 -0
package/dist/browser/index.html +2 -2
package/dist/cli.cjs +43922 -80546
package/dist/electron.cjs +42950 -79935
package/dist/views/text/index.html +38 -0
package/dist/views/text/manifest.json +5 -0
package/package.json +26 -15
package/skill/SKILL.md +365 -100
package/dist/artifact-runtime/index.js +0 -986
package/dist/artifact-runtime/style.css +0 -1
package/dist/browser/assets/index-C0Ygc25s.js +0 -555
package/dist/browser/assets/index-D0BGTUk2.css +0 -1

package/skill/SKILL.md CHANGED Viewed

@@ -1,171 +1,283 @@
 # Television
-Television is a virtual display for showing persistent artifacts to a user. Use Television whenever you want to visualize something for the user instead of only describing it in text.
+Television is a persistent artifact screen for agents. Use it when the user
+should be able to inspect, revisit, and refine a file-backed result instead of
+only reading a chat reply.
-## Check whether it is running
+If you lose context, run:
 ```bash
-tv status
+tv help
 ```
-This reports whether the server is healthy and whether it's installed as a system service. If the server is not reachable, start it:
+That command prints this full skill as one blob. There is no topic-scoped help
+in the current implementation.
-```bash
-tv serve
-```
+## Mental model
-If you need it to keep running while you do other work, start `tv serve` in a background terminal, or install it as a service with `tv serve --persist`.
+- A **screen** is the screen and layout container.
+- An **artifact** is one displayed result on that screen.
+- An **internal artifact** is a Television-managed bundle. You create a pending
+  bundle, edit files in that bundle, then commit it.
+- An **external artifact** is a pointer to an existing absolute file on disk.
+  Television displays that file but does not own or delete it.
+- **Pending** means a create or edit is staged but not yet committed.
+- **Trash** means metadata and committed internal bundles moved out of the live
+  tree. There is no restore workflow in the current scope.
-## Artifact types
+The core workflow is:
-All artifacts have:
+1. Decide whether the result should be internal or external.
+2. Create or stage the artifact with the CLI.
+3. For internal artifacts, edit files in the pending bundle.
+4. Commit when the validation rules are satisfied.
-- `type`: the type string (`markdown` or `html`; defaults to `markdown`)
-- `title`: user-visible title shown in the workspace
-- `path`: absolute file path to the artifact source on disk
+## User communication during multi-step workflows
-### Markdown (default)
+When you are doing a multi-step artifact workflow, keep the user informed as you
+progress.
-Use this for documents, reports, plans, status updates, or any content that benefits from readable prose formatting.
+Required communication style:
-Properties:
+- verbalize key actions and decisions as they happen
+- keep the language concise
+- prefer short updates over long explanations
+- frame updates in the user's world and goals, not in the internal mechanics of the skill or CLI workflow
+- avoid technical workflow jargon unless the user explicitly asks for it
+- do not write reports, long paragraphs, or chatty summaries while the work is in progress
+- do not use lists unless the user explicitly asks for one
+- optimize for speed and token efficiency
-- `type`: `markdown`
-- `path`: absolute path to a `.md` file
+Good examples:
-### HTML
+- "Starting the artifact now."
+- "Reviewing the draft and source material."
+- "Updating the HTML and efficiently navigating the artifact creation flow."
+- "The artifact did not pass validation yet; fixing the draft notes and retrying."
+- "Finalizing the artifact now."
+- "Done."
-Use this for structured layouts, dashboards, data displays, or anything that needs precise visual control.
+Bad examples:
-Properties:
+- multi-paragraph progress reports
+- long retrospective narration during execution
+- verbose bullet lists for routine workflow steps
-- `type`: `html`
-- `path`: absolute path to an `.html` file
+## Internal versus external
-HTML files should still be body-fragment style content for Television artifact rendering, not full standalone HTML documents.
+Use an **internal artifact** when:
-```html
-<!-- Bad — rejected -->
-<!doctype html><html><body><p>Hello</p></body></html>
+- the artifact is purpose-built for Television
+- Television should own the bundle structure
+- future agents should be able to maintain the result by reading bundle files
+- you need a staged create or staged edit workflow
-<!-- Good -->
-<p>Hello</p>
-```
+Use an **external artifact** when:
-## Commands
+- a real file already exists on disk
+- the user wants Television to display that existing file
+- you do not need a Television-managed bundle
-All commands output JSON. If you need to target a non-default server, add `--server "http://host:port"` to any command except `serve` and `stop`.
+Decision rule:
-When only one workspace exists, `--workspace` / `--id` can be omitted and it will be selected automatically.
+- If the result should be maintained as a Television-owned long-lived artifact,
+  choose internal.
+- If the result is already a real file outside Television and should stay that
+  way, choose external.
-### Start the server
+Supported artifact types:
-```bash
-tv serve
-tv serve --persist          # install as a background system service
-tv serve --port 3000        # custom port
-tv serve --public           # no auth (open access)
-```
+- `text/markdown`
+- `text/html`
-### Stop the system service
+## Internal bundle files
-```bash
-tv stop
-```
+Every internal artifact bundle contains:
-### Check server status
+- `artifact.md`
+- `data.json`
+- `memory.md`
+- `public/index.md` or `public/index.html`
-```bash
-tv status
-```
+Fresh pending bundles are intentionally minimal:
-### List workspaces
+- `artifact.md` is blank
+- `memory.md` is blank
+- `public/index.md` or `public/index.html` is blank
+- `data.json` is exactly `{}`
-```bash
-tv list-workspaces
-```
+The scaffold is not commit-valid by itself. Learn the required structure from
+this skill, not from placeholder content in the scaffold.
-### Get a workspace and its artifacts
+### `artifact.md`
-```bash
-tv get-workspace
-tv get-workspace --id "workspace-id"
+`artifact.md` is the contract for the artifact. It explains what the artifact
+is for, what conceptual material it is based on, how it should render, and how
+later agents should maintain it.
+Before commit, `artifact.md` must be non-empty and contain all of these exact
+headings:
+```md
+## User intent
+## Purpose
+## Data shape
+## Data sources
+## Rendering
+## Update workflow
+## Non-goals
 ```
-This returns artifact metadata and file paths, not full artifact contents.
+What each section should capture:
-### Create an artifact
+- `## User intent`: faithful restatement or quotation of what the user actually said they wanted; this is critical and should preserve the user's language as closely as practical, including requests, feedback, complaints, constraints, and guidance
+- `## Purpose`: what the artifact is trying to achieve
+- `## Data shape`: the conceptual shape you reasoned about while authoring; for markdown artifacts this will often just be `{}`
+- `## Data sources`: where the underlying facts, notes, or source material came from and how they were obtained
+- `## Rendering`: how `public/index.md` or `public/index.html` should present it
+- `## Update workflow`: how future agents should refresh or modify it
+- `## Non-goals`: what is intentionally excluded, especially application-like runtime behavior
-```bash
-tv create-artifact --path "/absolute/path/to/plan.md"
-tv create-artifact --type html --path "/absolute/path/to/dashboard.html"
-tv create-artifact --path "/absolute/path/to/plan.md" --workspace "workspace-id"
-```
+### `data.json`
-Create the file first, then pass its path to Television.
+`data.json` is a **thinking artifact**, not a runtime payload.
-Validation rules:
+Its purpose is to help the model separate:
-- path must be absolute
-- markdown paths must end in `.md`
-- html paths must end in `.html`
-- file must exist
-- file must be readable
+- reasoning / planning / authoring structure
+- from final presentation in `public/index.md` or `public/index.html`
-Television stores artifacts as file pointers. If you need the artifact contents, read the file directly from the path.
+Use it to capture the pure conceptual shape of what you are about to render.
+This is an authoring aid for agents, not an application data layer.
-If validation fails, the CLI exits non-zero with a clear error.
+Hard rules:
-### Find the Television data directory
+- **Do not treat `data.json` as live runtime state.**
+- **Do not write HTML/JS that loads, depends on, or synchronizes against `data.json`.**
+- **Do not build application-like data-driven artifacts.**
+- **We do not support runtime data-backed artifacts at this time.**
+- Artifacts are static markdown or static HTML documents.
+- HTML artifacts may include JavaScript and extra assets under `public/`, but
+  that JavaScript must stay presentation-oriented and self-contained, not
+  driven by `data.json` as an application state container.
-```bash
-tv data-dir
+For `text/markdown` artifacts, leave `data.json` as exactly:
+```json
+{}
 ```
-Use this when the file belongs specifically to Television workspace state and does not already live in another project.
+There is usually little value in separating content from presentation for
+markdown artifacts, so prefer `{}` unless there is a very strong authoring
+reason not to.
-Guidance:
+For `text/html` artifacts, use `data.json` only when it helps you think clearly
+about the material before rendering. It may describe the conceptual structure
+of the artifact, but it must not become a runtime contract.
-- best: put the file somewhere in the user's actual files where it is relevant to the artifact's purpose
-- next best: put workspace-specific generated files in the Television data directory
-- third best: put the file in the OpenClaw workspace if it is just transient working material
+Validation rule:
-Do not put Television artifacts in a temp directory. Temp folders are an anti-pattern because the files are easy to lose and not meaningfully located.
+- `data.json` must exist and contain valid JSON
-Television does not own or delete the underlying files when artifacts are removed.
+The current validator does not require the JSON value to be an object, but an
+object is the normal choice.
-### Update an artifact
+### `memory.md`
-```bash
-tv update-artifact --id "artifact-id" --title "New title"
-```
+`memory.md` is the working scratchpad for later agents. Record decisions,
+limitations, data-retrieval notes, problems encountered, what changed, and what
+should be watched during future edits.
-### Remove an artifact
+Required validation anchors:
-```bash
-tv remove-artifact --id "artifact-id"
+- `memory.md` must contain `## Activity Log`
+- `memory.md` must contain at least one UTC timestamp in exact
+  `YYYY-MM-DDTHH:MM:SSZ` format
+- at least one timestamp must be from the last 30 minutes when you commit
+The minimum required heading is:
+```md
+## Activity Log
 ```
-## HTML artifact styling
+What to record beyond that is up to the artifact and the work performed.
+### `public/index.md` and `public/index.html`
+This is the rendered entry file that Television serves.
+- Markdown artifacts use `public/index.md`
+- HTML artifacts use `public/index.html`
+- the entry file must match the artifact `type`
+- the entry file must be non-empty before commit
+For HTML artifacts:
+- `public/index.html` is a full HTML document, not a body fragment
+- additional public assets may live under `public/`
+- keep paths relative to `public/`
+## Quality bar
+Build artifacts that are durable, truthful, and maintainable by later agents.
+Required quality standards:
+- be faithful to source data
+- do not invent or hallucinate missing facts
+- do not silently truncate a dataset and pretend it is complete
+- prefer truth over completeness when those goals conflict
+- make limitations, sampling, missing data, and freshness visible
+- keep rendering aligned with the reasoning captured in `artifact.md`, `data.json`, and `memory.md`
+- keep `data.json` as an authoring/thinking artifact rather than a runtime dependency
+- keep the artifact maintainable by a future agent reading only the bundle files
+Anti-patterns:
+- cursory or low-effort data collection
+- fake data added to make the artifact look complete
+- brittle one-off hacks that a later agent cannot reproduce
+- hidden dependencies that are not documented in `artifact.md` or `memory.md`
+- layout churn during simple data refreshes when the data model did not change
+## HTML house style
+HTML artifacts should feel intentional and readable inside Television tiles.
-HTML artifacts are rendered with a full base stylesheet. Only add custom CSS when you need something not covered here — prefer the built-in styles and variables to keep artifacts visually coherent with the rest of the system.
+Television provides a full base stylesheet for HTML artifacts. Only add custom
+CSS when you need something not covered by the built-in styles. Prefer the base
+styles and theme tokens so artifacts stay visually coherent with the rest of
+Television.
+House-style guidance:
+- use semantic HTML first
+- keep the most important information near the top
+- design for small, medium, and large tile sizes
+- avoid horizontal overflow unless there is no reasonable alternative
+- make empty states and error states explicit
+- prefer the built-in HTML styling before inventing custom component chrome
 ### Elements
-All standard elements get sensible defaults — you don't need to style from scratch:
+Standard elements already have sensible defaults, so you usually do not need to
+style from scratch:
-- Headings (`h1`–`h6`) — sized and weighted
+- headings (`h1`–`h6`) — sized and weighted
 - `p`, `ul`, `ol` — readable defaults
 - `code` and `pre` — monospace, muted background
 - `blockquote` — left border, muted text
 - `table`, `th`, `td` — bordered, striped headers
-- `button` — styled with border and hover state; use `size="sm"` or `size="md"` attribute
+- `button` — styled with border and hover state; use `size="sm"` or `size="md"` when appropriate
 - `hr` — subtle border
 - `a` — inherits color by default
 ### `.prose` class
-Adds document-style vertical spacing between block elements. Wrap long-form content in `<div class="prose">` for comfortable reading.
+Use a `.prose` wrapper for document-style HTML where readable vertical rhythm is
+appropriate. Do not rely on `.prose` for dashboards, tables, control surfaces,
+or dense custom layouts.
 ```html
 <div class="prose">
@@ -180,14 +292,15 @@ Adds document-style vertical spacing between block elements. Wrap long-form cont
 ### CSS variables
-Use these to stay consistent with the app theme.
+Use the existing Television tokens when they are available in the runtime.
+These are the preferred way to stay aligned with the app theme.
 Colors:
 - `--color-bg` — page background
-- `--color-bg-muted` — subtle background (used on code, table headers)
-- `--color-surface` — card/panel background
+- `--color-bg-muted` — subtle background
+- `--color-surface` — card or panel background
 - `--color-text` — primary text
-- `--color-text-muted` — secondary/label text
+- `--color-text-muted` — secondary or label text
 - `--color-border` — border color
 Spacing:
@@ -198,7 +311,7 @@ Spacing:
 - `--space-24`
 - `--space-32`
-Font:
+Fonts:
 - `--font-sans`
 - `--font-mono`
@@ -211,3 +324,155 @@ Text sizes:
 Radius:
 - `--radius-sm`
 - `--radius-md`
+## Workflows
+### Create new internal artifact
+1. Decide that the result should be an internal artifact.
+2. Start the pending bundle:
+```bash
+tv create-internal-artifact --screen "<screen-id>" --type text/markdown --title "Artifact title"
+```
+Or:
+```bash
+tv create-internal-artifact --screen "<screen-id>" --type text/html --title "Artifact title"
+```
+3. Read the returned pending path and edit files there.
+4. Write `artifact.md`.
+5. In `artifact.md`, capture the user's language faithfully in `## User intent` before doing the rest of the authoring work. Use direct quotes when helpful, or a close paraphrase when that is clearer, but keep it representative of what the user actually said they wanted.
+6. Think through the artifact in a pure way and write `data.json` only as an authoring aid.
+7. For markdown artifacts, leave `data.json` as `{}` unless there is a compelling authoring reason not to.
+8. Render `public/index.md` or `public/index.html`.
+9. Append a current timestamped activity entry in `memory.md`.
+10. Commit:
+```bash
+tv commit-pending-artifact --id "<artifact-id>"
+```
+### Update internal artifact with fresh data
+1. Stage the edit:
+```bash
+tv edit-internal-artifact --id "<artifact-id>"
+```
+2. Read `artifact.md`, `data.json`, and `memory.md` before changing anything.
+3. Refresh the underlying facts or source material.
+4. Update `data.json` only if it helps clarify the authoring plan.
+5. For markdown artifacts, prefer to keep `data.json` as `{}`.
+6. Make the minimum rendering changes needed to keep the artifact correct.
+7. Record what changed in `memory.md`.
+8. Commit:
+```bash
+tv commit-pending-artifact --id "<artifact-id>"
+```
+Avoid unnecessary layout or styling churn during data-only refreshes.
+### Modify internal artifact from user feedback
+1. Stage the edit:
+```bash
+tv edit-internal-artifact --id "<artifact-id>"
+```
+2. Read `artifact.md`, `data.json`, and `memory.md`.
+3. Update `artifact.md` if the user intent or non-goals changed.
+4. When the user has added feedback, complaints, corrections, or new guidance, update `## User intent` so it remains a faithful record of what the user actually wants now. Preserve the user's language as closely as practical, using direct quotes or close paraphrases.
+5. Update `data.json` only if it improves the authoring model of the artifact.
+6. For markdown artifacts, prefer to keep `data.json` as `{}`.
+7. Adjust `public/index.md` or `public/index.html` as narrowly as possible.
+8. Record the request, decision, and resulting change in `memory.md`.
+9. Commit:
+```bash
+tv commit-pending-artifact --id "<artifact-id>"
+```
+### Abandon pending work
+If the staged work should be discarded instead of committed:
+```bash
+tv abandon-pending-artifact --id "<artifact-id>"
+```
+### Create external artifact
+Use this when the file already exists on disk and Television should display it
+without owning a bundle:
+```bash
+tv create-external-artifact --screen "<screen-id>" --type text/markdown --title "Artifact title" --path /absolute/path/to/file.md
+```
+Or:
+```bash
+tv create-external-artifact --screen "<screen-id>" --type text/html --title "Artifact title" --path /absolute/path/to/file.html
+```
+Rules:
+- `--path` must be absolute
+- the file must already exist and be readable
+- the extension must match `type`
+- external artifacts do not use pending create, pending edit, commit, or abandon
+## CLI reference
+Workflow commands:
+```bash
+tv create-internal-artifact --screen "<screen-id>" --type <text/markdown|text/html> --title "Artifact title"
+tv edit-internal-artifact --id "<artifact-id>"
+tv commit-pending-artifact --id "<artifact-id>"
+tv abandon-pending-artifact --id "<artifact-id>"
+tv create-external-artifact --screen "<screen-id>" --type <text/markdown|text/html> --title "Artifact title" --path /absolute/path
+tv update-artifact --id "<artifact-id>" --title "New title"
+tv remove-artifact --id "<artifact-id>" --screen "<screen-id>"
+tv remove-screen --id "<screen-id>"
+```
+Read and server commands:
+```bash
+tv list-screens
+tv get-screen --id "<screen-id>"
+tv create-screen --name "Screen name"
+tv storage-path
+tv status
+tv serve
+tv stop
+```
+CLI behavior notes:
+- workflow and mutation commands print plain text
+- read commands print JSON
+- `tv get-screen` includes artifact `kind` and `status`
+- `tv remove-artifact` removes the artifact reference from the named screen; if another screen still references it, the artifact is unlinked and kept alive; otherwise it cascades to trash/discard
+- `tv update-artifact` changes title metadata only
+- when the CLI reports an error, follow the directive to run `tv help`
+## Deferred or out of scope
+These are not part of the current implementation:
+- `tv help <topic>`
+- restore-from-trash
+- pending-listing commands
+- attestation or nonce commands
+- stale pending cleanup or stale trash cleanup
+- markdown editor UI recovery
+- client-side pending presentation work
+- multi-section help output