NAME
Developer::Dashboard::PageRuntime - older bookmark renderer and CODE executor
SYNOPSIS
my $runtime = Developer::Dashboard::PageRuntime->new(paths => $paths);
$runtime->prepare_page(page => $page, source => 'saved');DESCRIPTION
This module applies Template Toolkit rendering to bookmark HTML and executes older CODE* blocks while capturing STDOUT and STDERR for in-page display. For skill pages, it loads the ordered skill .env and .env.pl files into a request-local environment overlay while CODE executes, without changing the web worker environment. Saved skill Ajax processes receive the same layered values through their child environment. Skill lib/ directories are also scoped into @INC, with the page-providing skill first. Each CODE block imports j and je from Developer::Dashboard::DataHelper automatically, so saved code does not need to repeat that import. Skill CODE can also read request-local Dancer2 app variables established by skill hooks by importing the existing app, for example use Dancer2 appname => 'DeveloperDashboard'; print var('foo');. The matching skill extension must register its hook with the Dancer2 form hook before => sub { var foo => 'bar' }; a bare before => sub { ... } expression does not register a hook.
METHODS
new, prepare_page, run_code_blocks, stream_code_block, stream_saved_ajax_file
Construct the runtime, render bookmark templates, execute in-process CODE blocks, and stream saved Ajax files as real child processes. Skill page CODE receives the skill's layered env values and skill libraries for the duration of its execution only; saved skill Ajax workers receive the layered env values in their child process. Page and Ajax CODE runs execute within the active Dancer2 request context, so imported var() can read values set by a skill's before hook. On POSIX systems each saved Ajax worker runs inside its own process group, and disconnect or stream-error cleanup signals that whole group so descendant processes forked by the worker terminate with it; Windows keeps direct child-process termination. Cleanup sends SIGTERM first and then waits a bounded, elapsed-time grace window for the worker and its group to exit on their own, so a worker that installs a SIGTERM handler can reap its children, remove scratch files, and flush partial output before the SIGKILL escalation clears whatever is left.
_template_include_roots
Builds the safe Template Toolkit INCLUDE_PATH for a bookmark. It includes the ordinary layered dashboard roots, the active skill's dashboards root, and the runtime roots so a skill template can explicitly include skills/foo/dashboards/fragment.tt. Relative includes such as fragment.tt continue to resolve from the current skill dashboard first.
Input: page document, optionally carrying meta.skill_path. Output: ordered list of include-root directory paths.
PURPOSE
This module executes and renders dashboard bookmark pages. It evaluates bookmark directives, runs code blocks, exposes browser-side helper functions such as fetch_value, stream_value, and stream_data, and returns the HTML fragments or runtime errors that the web layer displays.
WHY IT EXISTS
It exists because bookmark execution is the heart of the product. Rendering, code execution, helper injection, and runtime state all need one owner so saved pages, transient pages, and seeded workspaces behave consistently.
WHEN TO USE
Use this file when changing bookmark rendering, Template Toolkit exposure, code-block execution, automatic DataHelper imports, or Ajax helper generation.
HOW TO USE
Construct it with the file and path registries plus any path aliases, then feed it a normalized page document. Every CODE block receives the standard Developer::Dashboard::DataHelper qw(j je) import. For skill pages, the exact skill layer that supplied the page is the first scoped @INC entry, followed by the other active skill layers, so module lookup respects the page provider before inherited skill libraries. Let the runtime return render fragments or errors rather than building bookmark execution logic in routes or helper scripts.
WHAT USES IT
It is used by the web app render/source/edit flows, by skill bookmark rendering, by seeded dashboard pages, and by a large body of page/web regression tests.
EXAMPLES
Example 1:
perl -Ilib -MDeveloper::Dashboard::PageRuntime -e 1Do a direct compile-and-load check against the module from a source checkout.
Example 2:
prove -lv t/07-core-units.t t/21-refactor-coverage.tRun the focused regression tests that most directly exercise this module's behavior.
Example 3:
HARNESS_PERL_SWITCHES=-MDevel::Cover prove -lr tRecheck the module under the repository coverage gate rather than relying on a load-only probe.
Example 4:
prove -lr tPut any module-level change back through the entire repository suite before release.