Report Issue Local

When to use

Something in this toolkit is wrong or missing: a drawing primitive produces incorrect pixels, PixooClient mishandles a device response, a color or font renders differently than documented, an export encoder emits a malformed file, or a capability the toolkit should have does not exist.

Triage first — not every Pixoo problem is a toolkit problem:

Before filing

1. Search existing issues — including closed ones. This repo has a dense history of narrow, closed bug reports, and a new symptom is often a regression of one:

gh issue list --repo cyanheads/pixoo-toolkit --search "<symptom or function name>" --state all
gh issue view <number> --comments

If a close match exists, comment on it rather than filing a duplicate — unless the scope is genuinely distinct. A previously closed issue that has regressed gets a new issue labeled regression, cross-linked to the original.

2. Reproduce it. Reduce to the smallest snippet that shows the defect. A reproduction that needs a physical device is much weaker than one that does not — most of this toolkit is pure functions over a pixel buffer, so push the repro toward Canvas + savePng() and away from PixooClient wherever the defect allows.

3. Confirm expected behavior against a source, not intuition. For device commands that is the API reference in CLAUDE.md; for rendering it is the documented behavior in README.md or the existing test in tests/.

Redact before posting

This repo is public and its subject is a device on a home network.

• Never post a real device IP. Use <device-ip> or a TEST-NET address (192.0.2.1), matching .env.example.
• Strip device IDs, MAC addresses, Divoom account identifiers, tokens, and Wi-Fi network names from logs and JSON payloads before pasting them.
• Do not partially mask — replace the whole value with REDACTED.

Filing

The repo ships YAML issue forms. Use --web to fill the form interactively, or match its field headings in a --body for non-interactive filing.

gh issue create --repo cyanheads/pixoo-toolkit --template "Bug Report" --web

Non-interactive — always route the body through a quoted-delimiter heredoc or --body-file. Passing markdown as a quoted argument corrupts it: backticks inside double quotes run as command substitution and silently delete the code spans.

gh issue create \
  --title "bug(canvas): drawRect ignores non-finite dimensions" \
  --label "bug" \
  --assignee "cyanheads" \
  --body "$(cat <<'ISSUE'
### Toolkit version

0.7.7

### Runtime

Bun

### Runtime version

Bun 1.3.x

### Subsystem

Canvas and drawing

### Device model

Not device-related

### Description

`drawRect()` accepts a `NaN` width and returns normally without writing any pixels, so a caller with a bad computed dimension sees a silent no-op instead of an error.

### Reproduction

```typescript
import { Canvas } from '@cyanheads/pixoo-toolkit';

const canvas = new Canvas(64);
canvas.drawRect(0, 0, NaN, 10, 'red');
```

### Actual behavior

```
No pixels written, no error thrown.
```

### Expected behavior

`RangeError`, matching how `drawCircle()` and `drawLine()` reject non-finite input.

### Additional context

Sibling primitives gained non-finite guards in #17, #23, and #24; `drawRect()` was not covered.
ISSUE
)"

Every issue is assigned to cyanheads at creation. Pass --assignee cyanheads on every gh issue create call in this repo.

Titles

Format: type(scope): description

• type: bug, feat, docs, chore, security
• scope: the src/ module — canvas, client, color, font, image, animation, preview, svg-path — or deps, packaging, types

Describe the observable defect, not the suspected cause. bug(color): hslToRgb returns out-of-range values for hues above 360 beats bug(color): modulo bug.

Examples:

• bug(svg-path): compact decimal coordinates parse to NaN ('l.5.5')
• feat(client): LAN device discovery
• bug(animation): mixed frame sizes produce invalid payloads

Labels

Exactly one primary label, plus any secondary that applies.

If gh reports label not found, create it once:

gh label create regression --color e99695 --description "Worked before, broken after a change"
gh label create performance --color 5319e7 --description "Memory, CPU, or latency"
gh label create security --color b60205 --description "Vulnerability, CVE, or hardening work"
gh label create breaking-change --color d93f0b --description "Requires a major bump"

Writing the body

Terse and fact-dense. One or two sentences per bullet; if a bullet runs long, split it or cut it.

• Lead with the specific. Name the exported function and the input that triggers it in the first sentence.
• Show the failing values. "Returns { r: 260, g: 0, b: 0 }" beats "returns wrong colors." For a rendering bug, state the coordinates and what is at them.
• Make the reproduction runnable. Fenced typescript, importing from the package barrel, no local paths.
• Separate ### Scope from ### Out of scope on feature requests. The boundary pre-empts scope debate in the comments.
• Cross-reference once. Link a related issue in one place — Related: #N near the top, or in the body — not in three.
• Cut the noise. No mechanism walkthroughs, no "This issue covers…", no conversation references, no "happy to open a PR" sign-offs. End at the last substantive point.

For a feature request, the form asks for a Proposed API — write the consumer-facing TypeScript, not a description of it:

// what the caller writes
canvas.drawPolygon([[0, 0], [10, 0], [5, 8]], 'cyan', { fill: true });

Following up

gh issue view <number> --comments
gh issue comment <number> --body "Additional findings..."
gh issue close <number> --reason completed --comment "Fixed in v0.7.8."

Reading an issue means the body and the thread — gh issue view N --comments shows only the comments, so run both, or gh api repos/cyanheads/pixoo-toolkit/issues/N for the combined view.

Checklist

• Triaged — the defect is in this toolkit, not firmware or an upstream dependency
• Searched open and closed issues; close matches commented rather than duplicated
• Device IPs, IDs, and credentials redacted
• Title follows type(scope): description with a src/ module scope
• Exactly one primary label; regression added if it previously worked
• --assignee cyanheads passed
• Body sent via heredoc or --body-file, never a quoted markdown argument
• Bug: version, runtime, runnable repro, actual vs expected
• Feature: Proposed API in TypeScript, Scope and Out of scope defined