Skip to content

feat(dashboard): per-type renderers for every dashboard package block - #18784

Closed
chenmingwei23 wants to merge 2 commits into
feat/18642-dashboard-write-modelfrom
feat/18642-dashboard-renderers
Closed

chenmingwei23 wants to merge 2 commits into
feat/18642-dashboard-write-modelfrom
feat/18642-dashboard-renderers

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: a validated dashboard package becomes a page a crewmate can read, with
one renderer per block type and no block silently drawn as something else.

The stack below gives a layout package a validated home and a model reader, but
nothing turns a package into HTML: a view names block types and the fields
each shows, a model says what type every field is, and no code maps either to
markup. So a composed package has no page.

The catalog below this PR is also a four-type stub (stat, table, list,
timeline), and every type an agent is offered must actually draw: a catalog
type with no renderer validates on write and then appears as an empty box on
somebody's dashboard.

Why it matters

A dashboard is only worth the trust a reader puts in it, and the ways markup
betrays that are specific. A number without its unit reads as a different
quantity; a timestamp drawn as a number reads as a count; a block whose type has
no renderer leaves a hole that looks like missing data rather than a missing
feature. None of those is visible in a diff, which is why this PR's evidence is
38 rendered captures rather than assertions alone.

Not a goal

  • No frontend: mounting the rendered page in the Dashboard tab is the frontend PR's.
  • No server push: which blocks a fold advances, and publishing the patch, is the block-push PR's.
  • No new data types. The field vocabulary stays as the package defines it; this PR widens only the BLOCK catalog.
  • No agent-authored code or network. The page runs under the document's own CSP, and the two vendored libraries are committed, pinned and served locally.

What changed (motivation -> approach -> change)

Goal: every block type a package may name draws its own markup.

Approach. A chain of conditionals inside one render function is how a type ends
up half-handled, so instead there is one formatter table keyed by field type and
one renderer table keyed by block type, and a test asserts each table's keys ARE
the corresponding catalog. A type added to a catalog with no renderer is then a
test failure here rather than an empty box on a dashboard.

  • src/kiro_crew/dashboard_package_render.py (new): per-type renderers for
    every block type and per-type formatters for every field type. A number
    carries its unit and honours precision; a timestamp renders as <time>;
    an enum renders against its choices, and a value outside them is SHOWN,
    because a fold disagreeing with the model is information.
  • The block catalog widens from the four-type stub to the full set, and
    view_block_catalog() stays the single point of truth: validation, the JSON
    Schema and the dispatch table all read that one function.
  • block_patch() renders one block's values, so a page updates in place without
    re-initialising the whole document.
  • Two libraries are vendored under dashboard_package_vendor/
    (anime-3.2.2.min.js, three-0.159.0.min.js) with their licences and the
    MANIFEST.in / setup.cfg entries that ship them. Committed and served
    locally because the page's CSP allows no network, so a CDN reference would
    silently fail to load.
  • Reduced motion is honoured: the animated blocks draw a flat form under
    prefers-reduced-motion rather than animating anyway or disappearing.

Backwards compatibility

Compatible with ONE exception: dashboard_package_render is a new module with no
prior callers, and widening view_block_catalog() otherwise only makes valid
what the stub refused. The exception is timeline, which requires a
timestamp among its fields -- nothing to order by without one -- so a timeline
carrying none is refused where the stub accepted it. The setup.cfg /
MANIFEST.in entries add files and remove none.

Tightened, once: revert_package() REFUSES a revert whose live package does
not parse, rather than falling back to the target version's own bound_to. The
evidence is this PR's own review finding that the fallback rebinds wrongly:
bound_to is the one field a revert must not restore, so an unreadable live
copy has no live binding to keep, and taking the target's can hand the page to
whoever that stale binding named -- silently. Its only caller is the store's
dashboard revert; a readable live package is unaffected.

Removed, both unreachable: block_catalog_summary(), whose only caller was
its own test (now reading the catalogs directly), and the repo-wide
':(exclude)*.min.js' pathspec -- every minified file in the tree sits under a
vendor directory the scan already excludes. Both vendor exclusions stay.

Fixed: a timestamp's day comes from moment.day, not strftime, so the
string no longer differs by platform. %-d is a glibc extension Windows
rejects, which gave "Oct 9" here and "Oct 09" there and made the formatter test
red on Windows. _supports_dash_d() goes with it.

Otherwise additive; one test moved rather than vanished, see Tests.

Tests

pytest -n 2 -q --color=no -p no:cacheprovider \
  test/test_dashboard_package_render.py test/test_artifact_dashboard_package.py
251 passed in 4.05s                        (exit 0)

What they lock in: every block type renders its own markup, parameterised over
the whole catalog, asserting the type's own class AND the absence of the
unrenderable fallback class; the formatter table's keys ARE
data_type_catalog(); the catalog is no longer the four-type stub, asserted as
a property rather than a frozen list; a value outside an enum's choices is
shown, not dropped; one block's patch leaves its neighbours alone.

One test moved rather than being deleted. The pin that the JSON Schema's
block enum equals this PR's BLOCK_TYPES now lives beside the generator in
#18760, against the catalog FUNCTIONS rather than a frozen list, so it keeps
holding as this PR widens the catalog.

The suite was shown able to fail: pointing the timestamp formatter at
_format_number gives 2 failed. The mutation was reverted and the restore
sha256-verified.

Gates all exit 0: flake8, isort --check-only, black --check, mypy, the
comment-history gate with its self-test, take-away and fold-catalogue.

Manual verification

Each captured page is the actual HTML this module produced for a validated
package, loaded in a browser with the document's own stylesheet and the vendored
scripts, not a mock. The VALUES are fixtures, so they prove only that the
renderer's rules formatted them. A probe recorded computed styles per shot, so
"the token reached the page" is checked rather than eyeballed; that file is in a
PR comment.

Screenshots / video

All 38 are on branch screenshots/18642-renderers with the full caption
table; this branch carries no images. Load-bearing shots are inline.

R1 -- every block type renders its own markup. One pair per type in the
branch README, both themes, because the renderers read theme tokens.

stat, dark
table, light

R3 -- a page is patched one block at a time. Only the patched block's
values changed; no other block re-initialised.

the stale band
reduced motion

R5 -- theme tokens apply, and a hostile one is dropped. A token trying to
close its own CSS declaration is dropped and the page still renders.

tokens applied
hostile token dropped

Related Issues

Refs #18642
Depends on #18707

The T3 one-pager for #18642 was approved, so this line opens its PRs.

Pattern harvest

Not generalizable: a new rendering surface, not a fix. The habit worth naming
is already enforced by the dispatch-table tests above.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; style guidelines followed
  • Documentation updated where applicable
  • No secrets, credentials or internal references in the diff

Contribution License Agreement

I confirm that this contribution is made under the terms of the Apache-2.0
license, per the Licensing section of CONTRIBUTING.md.

@chenmingwei23
chenmingwei23 requested review from a team and KiroCrewCaptain as code owners October 10, 2026 08:06
@chenmingwei23
chenmingwei23 requested review from buluoray and removed request for a team October 10, 2026 08:06
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 10, 2026
@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 1303279ce9a3a2978c6df1d1b4f0fcd71ab2538f touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — 🔴 BLOCK

Premise-level review of 1303279ce9a3a2978c6df1d1b4f0fcd71ab2538f — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: BLOCK

The orbit 3D block and the 668 KB three.js bundle vendored only for it have no named harm; patch routing is work the description assigns to a later PR.

Not justified as shipped

  • Item 3 — oversized: orbit, "a turnable 3D ring", is a new block type, and _NEEDS_THREE = {"orbit"} makes it the only user of three.js. "Every type an agent is offered must draw" holds only because this PR offers it, and bars/gauge already draw numbers.
    Subtraction: delete orbit, _render_orbit, its WebGL JS, three-0.159.0.min.js, LICENSE-three.js.txt and the r159 README section.
    Clears when: the orbit block and three.js are removed, or a human amends the Goal.
  • Item 4 — oversized: anime.js is optional by the code's own design. The diff's if (still || typeof anime !== 'function') { fillEl.style.width = target; ...} draws without it, and it is inlined into every page.
    Subtraction: delete anime-3.2.2.min.js and its licence, and keep the direct-style path.
    Clears when: the library is removed, or a named reader harm from bars that appear without animation is cited.
  • Item 6 — oversized: blocks_reading and block_patch have 0 production consumers (grepped across src/). They are "which blocks a fold advances", which ## Not a goal assigns to "the block-push PR's".
    Subtraction: move blocks_reading, block_patch and BLOCK_PATCH_MESSAGE_TYPE to that PR.
    Clears when: they are deferred, or a human amends the Goal.
  • Item 5 — undeclared: the description says "nothing that validates today stops", but timeline now has requires={"timestamp"} and an accepts set without number or bool. A package stored under feat(artifacts): a validated, versioned dashboard layout package #18705 (on main) with a numeric timeline now fails validation.
    Clears when: the compatibility claim matches the diff, or the gate is limited to the new types.
  • Item 7 — inherited, rides along: the description's own evidence for refusing a revert is "this PR's own review finding". It deletes the docstring that pinned the old fallback: "falls back to the target's own binding: there is no live binding to preserve."
    Clears when: a failing case or a linked issue shows the fallback rebinding wrongly.

What this change ships

Inventory (8 items) — 3 justified

Intent: turn a validated dashboard package into a readable HTML page, one renderer per block type. ADDITION.

  1. Each package block type draws its own markup, plus a placeholder naming any unknown type — justified
  2. Field values format by type (unit, precision, <time>, out-of-choice enum shown) — justified
  3. New 3D "orbit" block with three.js bundled — oversized
  4. Bars and gauges animate through bundled anime.js — oversized
  5. Five more 2D block types, plus a gate refusing fields a block cannot draw — undeclared
  6. One block can be patched without reloading the whole page — oversized
  7. Reverting while the live package is corrupt is now refused — rides along
  8. Vendor files ship in the sdist/wheel and are excluded from the term scans — justified

Blockers

  • Item 3: shipping nothing costs nobody anything. The only support given is "every type an agent is offered must actually draw", and that applies only because this PR adds the type. No reader harm is named for a 3D ring of single values, and its cost is 668 KB of pinned, outdated third-party code.
    Subtraction: delete orbit and the three.js vendor files.
    Clears when: the orbit block and three.js are removed, or a human amends the Goal.

[FIRST-PRINCIPLES-REVIEWED] 1303279

Description read

[DESCRIPTION-READ] 43a50f79d7acdcf28c14f9a51696400844d7cbe7fb6df8c7c640e8807962372b

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — 🟡 CONCERNS

Design-level review of 1303279ce9a3a2978c6df1d1b4f0fcd71ab2538f — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: CONCERNS

The description claims removals that are not in this diff: block_catalog_summary(), _supports_dash_d() and the *.min.js pathspec do not exist on the base and are not removed here.

Watch

  • The description promises things the diff doesn't do. The ## Backwards compatibility section says it removed block_catalog_summary(), removed the repo-wide ':(exclude)*.min.js' pathspec, and dropped _supports_dash_d(). None of these exists in the base tree. The code-review.yml hunk only adds ':(exclude)src/kiro_crew/dashboard_package_vendor/**', and nothing is deleted. A reviewer who trusts the take-away list is checking readers of symbols that were never there. The real tightening, where revert_package now refuses an unparseable live package, is buried in the same list.
    Clears when: the Backwards compatibility section lists only what this diff removes or tightens: the revert_packagerefusal, with its readersrc/kiro_crew/artifacts.py:updateand the testtest_artifact_dashboard_package.py that covers it.
  • The 38 captures can't be checked. The evidence list shows 0 downloaded or committed images. The captures live only on screenshots/18642-renderers, which is outside this PR. Nothing under website/src/ changes, so this isn't a blocker, but the claim that "the renderers read theme tokens", covered by R1 and R5, has no rendered proof attached to this revision.
    Clears when: the R1/R5 captures are attached to the description as user-attachments, or committed under .github/screenshots/ in this PR.

[DESIGN-REVIEWED] 1303279

Description read

[DESCRIPTION-READ] f90ed025d6c67202203813362cfa4e31ff2d65a7dd3cc8a673d5dd545f5d725d

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 1303279ce9a3a2978c6df1d1b4f0fcd71ab2538f — this comment is updated in place on each push.

Review details

No findings that block the merge.

FINDING — src/kiro_crew/dashboard_package_render.py:1095 — a refill (a full-read MESSAGE or a block patch) only rewrites node.textContent = shown(name);. The holder's data-pkg-state is set once by _value_cell, so when an enum goes from "passed" to "failed" the chip reads "failed" but keeps the green good glyph and border. Bool on/off has the same problem. → Fix: in fill(), recompute data-pkg-state on .pkg-v--enum/.pkg-v--bool holders. The _ENUM_STATES buckets could ship in the island, or the patch could send the state alongside display.
FINDING — src/kiro_crew/dashboard_package_render.py:70 — the RENDER_CSP comment says it "adds exactly two things … Nothing else is granted", but the policy also grants "img-src data:" and "font-src data:". This is a security comment that contradicts the code (recurring-defect-patterns). → Fix: make the comment list all four grants, or drop the two data: grants if nothing needs them.

[OPUS-REVIEWED] 1303279

Verdict parsed from the review's SHA-scoped output markers for commit 1303279ce9a3a2978c6df1d1b4f0fcd71ab2538f.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 1303279ce9a3a2978c6df1d1b4f0fcd71ab2538f: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 1303279ce9a3a2978c6df1d1b4f0fcd71ab2538f and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 1303279

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 1303279ce9a3a2978c6df1d1b4f0fcd71ab2538f: <one-sentence reason>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 10, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/18642-dashboard-write-model branch from 7aa51dc to fddc0ea Compare October 10, 2026 09:39
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 10, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/18642-dashboard-write-model branch from fddc0ea to b8cd232 Compare October 10, 2026 11:51
@chenmingwei23
chenmingwei23 force-pushed the feat/18642-dashboard-renderers branch from 8ed8ff0 to c553bb1 Compare October 10, 2026 12:06
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 10, 2026
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Oct 10, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/18642-dashboard-write-model branch from b8cd232 to 17ce3eb Compare October 10, 2026 15:14
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 10, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/18642-dashboard-renderers branch from c553bb1 to 6aeec47 Compare October 10, 2026 15:30
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Oct 10, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/18642-dashboard-write-model branch from 84e5e19 to 5ce145d Compare October 10, 2026 21:46
@chenmingwei23
chenmingwei23 force-pushed the feat/18642-dashboard-renderers branch from 4d7bf2f to 42f6ae9 Compare October 10, 2026 21:48
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 10, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/18642-dashboard-write-model branch from 5ce145d to 299c440 Compare October 11, 2026 00:09
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 11, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/18642-dashboard-write-model branch from 299c440 to 0f8929a Compare October 11, 2026 00:52
@chenmingwei23
chenmingwei23 force-pushed the feat/18642-dashboard-renderers branch from 42f6ae9 to 4ae57d9 Compare October 11, 2026 00:54
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Oct 11, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/18642-dashboard-write-model branch from 0f8929a to 1eaa70c Compare October 11, 2026 05:32
@chenmingwei23
chenmingwei23 force-pushed the feat/18642-dashboard-renderers branch from 4ae57d9 to 05ab809 Compare October 11, 2026 05:33
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision labels Oct 11, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/18642-dashboard-write-model branch from 1eaa70c to 0e8df76 Compare October 11, 2026 05:42
The block catalog in the dashboard package was a four-entry stub whose own
docstring said the display line owns it. This fills it in and adds the other
half: a renderer per block type, and a rendering for every data type each
block admits.

`view_block_catalog()` now holds ten block types -- stat, stat_band, table,
list, note, bars, gauge, pills, timeline, orbit -- and each carries `accepts`,
the data types it can draw. That is a GATE: `_validate_view` refuses a block
naming a field it cannot draw (a bar chart over a line of text), and refuses a
timeline with no timestamp to order by. Without it the catalog could only
describe the limit in prose, and a block that silently dropped a field would
render a blank cell with every gate green.

`kiro_crew.dashboard_package_render` builds the whole document. Its CSP starts
at `default-src 'none'` and grants inline script and inline style only -- no
origin, no connect-src, no unsafe-eval -- so three.js r159 and anime.js 3.2.2
are vendored into `dashboard_package_vendor/` byte-identical to their npm
tarballs, licences intact, and inlined. three.js only for a view that has a 3D
block, which is a 650 KB difference.

Theme tokens are re-checked at render time over the bytes about to be written,
not trusted from the write gate: a token whose value could close its own
declaration, or CSS that fetches or leaves the stylesheet, is dropped and the
page still renders. `display_values` is the one formatter, in Python, so a cell
and the number inside a chart cannot disagree.

Tests enumerate the catalogs rather than restating them, in both directions: a
block type with no renderer and a renderer with no block type both fail, and
every (block type, accepted data type) pair is rendered and looked for. Six
mutations were run to show the suite sees a failure; one of them found that the
type marker also appears as a CSS selector, so the central pin was asserting on
a string present in every document and has been moved to the class attribute.
The renderer could build a whole document and one block's markup, but the page
only initialised itself once. So a controller pushing an update to the blocks
that subscribe to an advancing fold had two problems: a 3D block repainted that
way got no scene, and a second initialisation pass would append a second canvas
and leave two scenes animating over each other.

Every painter now takes a root -- the document on first paint, one block's own
section on a patch -- and the 3D init is idempotent, so running it again over a
stage that already has a canvas does nothing. Repainting only the named blocks
is not just cheaper: repainting the rest would re-run their count-up animation
for numbers that did not change, which is the decoration the brief rules out.

`BLOCK_PATCH_MESSAGE_TYPE` is the wire type and `block_patch()` builds the
payload. It carries VALUES and never markup: the model and the view change only
when the package is versioned, and that is a reload, so a patch has nothing to
rebuild and this boundary cannot introduce an element. Each block gets only the
fields it renders, so a patch cannot leak a value onto a block the view never
put it on, and the strings come from `display_values` -- the same formatter the
first render used. `blocks_reading()` answers which blocks a set of moved fields
belongs to, so a caller holding a fold's new values does not also have to hold
the subscription map.

Verified in a real browser, not by string match: a patch posted from the parent
of a sandboxed frame moved 7 of 40 cells and left 33 alone, advanced seq 1842 ->
1843, rescaled all four bars in the group whose largest value moved, took the
ring from offset 94.75 to 34.85, and left exactly one canvas. A patch naming a
block the page does not have changed nothing, and a post from the page's own
window was ignored -- the sender check is now asserted against every type
branch, not one spelling of it.
@chenmingwei23
chenmingwei23 force-pushed the feat/18642-dashboard-renderers branch from 05ab809 to 1303279 Compare October 11, 2026 05:43
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 11, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Superseded: pages are agent-written HTML on the dashboard_frame contract; see #18642.

@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Oct 11, 2026
@bolichen97
bolichen97 deleted the feat/18642-dashboard-renderers branch November 6, 2026 07:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant