包简介

Deterministic HTML-first page maps for language models and browser agents.

README 文档

README

Turn static HTML into deterministic page context for LLMs.

Voyager Page Map (VPM) is a PHP library that parses static HTML into VPM/1: a semantic, HTML-first text representation designed to be included in an LLM prompt.

static HTML -> Voyager Page Map -> VPM/1 text -> your LLM or agent

VPM preserves the information needed to understand and address a page—its structure, readable names, controls, declared state, link destinations, and potential actions—while filtering implementation noise such as scripts, styles, metadata, and irrelevant wrappers.

Every retained node receives a document-local reference such as @e5. That reference can also be resolved to a CSS or XPath selector for the source DOM.

Voyager Page Map is the context layer between your HTML source and your LLM. It does not fetch pages, execute JavaScript, control a browser, or call a language model.

Why VPM?

Raw HTML contains presentation markup and implementation details that are often irrelevant to a language model. VPM produces a focused, predictable representation of page meaning and interaction without replacing familiar HTML semantics with a separate taxonomy.

Typical uses include:

giving an LLM page context for extraction, classification, summarization, or question answering;
grounding model output in explicit elements such as @e5;
exposing controls, destinations, and potential actions so an agent can plan an interaction that another runtime will execute;
creating deterministic semantic snapshots for tests or page-change analysis.

Requirements

PHP 8.3 or later
DOM extension
libxml extension

Installation

composer require north-foundry/voyager-page-map-php

Quick start

<?php

require __DIR__ . '/vendor/autoload.php';

use NorthFoundry\VoyagerPageMap\VoyagerPageMap;

$html = <<<'HTML'
<!doctype html>
<html lang="it">
<head>
    <title>Login</title>
</head>
<body>
    <main>
        <h1>Accedi</h1>
        <form aria-label="Login">
            <label for="email">Email</label>
            <input id="email" type="email" required>
            <button type="submit">Accedi</button>
            <a href="/reset-password">Password dimenticata</a>
        </form>
    </main>
</body>
</html>
HTML;

$pageMap = VoyagerPageMap::fromHtml(
    $html,
    baseUrl: 'https://example.com/login',
);

echo $pageMap->toText();

Output:

VPM/1
title Login
url https://example.com/login

@e1 page [lang=it]
  @e2 main
    @e3 h1 "Accedi"
    @e4 form "Login"
      @e5 input "Email" [type=email, required, empty] {?fill, ?clear, ?focus}
      @e6 button "Accedi" [type=submit] {?click, ?focus}
      @e7 a "Password dimenticata" -> /reset-password {?click, ?open}

Give the page map to an LLM

VPM is model-provider agnostic. Include the serialized page map in the prompt sent through the client of your choice:

$pageContext = $pageMap->toText();

$prompt = <<<PROMPT
You are given a semantic map of a web page.

Identify the email field.
Return only its @e reference.

$pageContext
PROMPT;

// Pass $prompt to the LLM client or prompt pipeline of your choice.

If the model returns @e5, use it to inspect the corresponding VPM element or recover its source-DOM selector:

$choice = '@e5';

$element = $pageMap->findByReference($choice);
$reference = $pageMap->ref($choice);

echo $element?->toText();
// @e5 input "Email" [type=email, required, empty] {?fill, ?clear, ?focus}

$selector = $reference?->cssSelector()
    ?? $reference?->xpathSelector();

echo $selector;
// #email

Selectors address the DOM from which that VPM document was created. Voyager Page Map does not execute the selected action.

Reading VPM/1

@e5 input "Email" [type=email, required, empty] {?fill, ?clear, ?focus}

@e5 is the element reference.
input preserves the native HTML tag.
"Email" is the resolved readable name.
[...] contains semantic properties and static state.
{...} contains actions inferred from the markup.
?fill means that fill is possible but has not been runtime-verified; !action marks an action blocked by declared state.
-> /path identifies a navigation destination.

References are contiguous and deterministic for the same HTML and configuration. They are local to one VPM document and should not be treated as persistent IDs across page changes.

The complete grammar and retention rules are covered in the project documentation.

Configuration

Configurations are immutable and can be reused:

use NorthFoundry\VoyagerPageMap\Configuration\VoyagerPageMapConfiguration;

$configuration = VoyagerPageMapConfiguration::agent()
    ->withRelativeUrlResolution()
    ->withAttributes(['id', 'data-tracking'])
    ->withIgnoredSelectors(['.cookie-banner', '[data-testid="advertisement"]']);

$pageMap = VoyagerPageMap::fromHtml(
    $html,
    baseUrl: 'https://example.com/login',
    configuration: $configuration,
);

Available profiles:

default() and agent() produce the standard LLM-oriented representation.
compact() currently produces the same output as agent().
diagnostic() retains declared hidden elements, generic containers, and all source attributes.

Available modifiers:

withHiddenElements() retains elements declared with hidden or aria-hidden; hidden inputs remain excluded.
withGenericContainers() retains otherwise-promoted div and span elements.
withAttributes() includes all or selected source attributes.
withRelativeUrlResolution() compacts same-origin URLs relative to baseUrl.
withIgnoredSelectors() excludes every subtree matching one of the supplied CSS selectors.

Ignored selectors are evaluated against the parsed source DOM before references are allocated, so removed nodes do not leave gaps in @eN numbering. A matching element and all its descendants are excluded. Invalid selectors and browser-state selectors that cannot be evaluated against static HTML are rejected with an InvalidArgumentException.

VPM, VPMConfiguration, and VPMDocument are shorter aliases for the canonical class names.

Scope and limitations

Voyager Page Map analyzes only the supplied static HTML. It does not:

download or navigate to a URL;
execute JavaScript or inspect client-side state;
calculate layout, rendered visibility, occlusion, or pointer reachability;
verify whether an inferred action actually succeeds;
take screenshots or control a browser;
send data to an LLM.

HTML obtained through another HTTP or browser layer can still be passed to fromHtml().

VPM is not a sanitizer or redaction layer. Page text, textarea content, non-password input values, and explicitly selected attributes may appear in the output. Review or redact sensitive content before sending VPM to a third-party model provider.

Documentation

The VPM/1 specification and LLM integration guidance are available in the documentation directory.

Development

composer test
composer analyse
composer format:check
composer check

License

Voyager Page Map is released under the MIT License.

north-foundry/voyager-page-map-php 适用场景与选型建议

north-foundry/voyager-page-map-php 是一款基于 HTML 开发的 Composer 扩展包，目前已累计 0 次下载、GitHub Stars 达 0，最近一次更新时间为 2026 年 07 月 15 日，在 PHP 生态内属于活跃度较高的组件。

我们在过去多个企业项目中使用过 north-foundry/voyager-page-map-php 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 north-foundry/voyager-page-map-php 我们能提供哪些服务？

定制开发 / 二次开发

基于 north-foundry/voyager-page-map-php 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

north-foundry/voyager-page-map-php

包简介