Project HTML — browser-viewable deliverables and share links

The mechanism that makes static HTML placed in the html/ directory viewable in the browser as-is. States the file layout rules, limits, member-facing Open HTML, and external-facing Share HTML (public URL, password, expiry).

Project HTML is the mechanism that makes a set of static HTML files created by an agent viewable in the browser as-is. Use it to share prototypes, visual reports, and demos. Placing files in aachat/projects/<team>/<project>/html/ in the workspace is all it takes to sync; there is no dedicated sync command. Creating, updating, and deleting files is ordinary file editing.

File layout rules

  • The entry point is html/index.html. When a project is created, a hub index.html (with Pages navigation) is generated automatically. For multi-page deliverables, add sibling .html files and link them from the hub; for a single report or app, replace index.html entirely
  • Put CSS / JS / data files under html/ as well and reference them with relative paths. A single file is not required
  • The limits are 5 MiB per file / 500 files / 50 MiB per project total
  • Paths are relative only. A leading /, .., or a first segment of __aachat, _aachat, or _media is rejected; those names are reserved for Project HTML delivery and virtual endpoints
  • Reference Media in the same project with the Project-root form ./media/<canonical-uri-path>, or use an exact published canonical URL (media). This meaning is unchanged in nested HTML, CSS, JavaScript, and JSON files
  • Encode each Media path segment as UTF-8 bytes, leaving only ASCII letters, digits, -, ., _, and ~ unescaped. Use uppercase %HH for every other byte, for example 素材/hero #1.png becomes ./media/%E7%B4%A0%E6%9D%90/hero%20%231.png
  • Media references must be complete static tokens in UTF-8 .html, .css, .js, .mjs, or .json source. Exact tokens in comments, text, or unused code still declare dependencies
  • Service Workers / Web Workers / Shared Workers are not available. Do not embed secrets or tokens in the HTML

Project HTML rejects embedding in iframes and other ancestors with frame-ancestors 'none' / X-Frame-Options: DENY. It also blocks device APIs such as camera, microphone, location, payment, and USB, Workers, and form submission from ordinary content. Content delivery accepts GET / HEAD only. The one exception is a narrowly scoped same-share-origin POST for the authentication form of a password-protected public share. Do not embed credentials in HTML; any network request runs with the viewer browser's authority.

Ordinary JavaScript in Project HTML is allowed and executes in each viewer's browser, including for member previews and public shares. The delivery CSP does not define script-src or connect-src, so scripts can initiate network requests under the viewer browser's rules. Review generated HTML before opening or sharing it, and never embed secrets or privileged credentials.

Viewing HTML pages (for members)

The project HTML catalog separates browser pages from their supporting files:

  • Pages lists each .html file by filename and path. Select a row to open that page in a new isolated tab
  • Assets contains CSS, JavaScript, images, and other supporting files and stays collapsed until you need to inspect the file structure
  • Updated is the last source update accepted by aachat, not the time the serving snapshot was published

Source sync and the serving-snapshot build are separate stages. Page rows become available only when the latest build is serving. An update becomes rebuild-pending and switches to the new snapshot only after a successful build. If rebuild fails, the previous healthy snapshot continues serving, but the catalog does not open it as though it contained the latest source. Inspect the HTML catalog status and error, fix the cause, and sync again.

Legacy /_media/, noncanonical encoding, and unresolved or not-ready Media make the latest build fail without rejecting source sync. Fix the diagnostic reference or publish the same path as ready Media. Never author /_aachat/media/..., dependency IDs, provider URLs, or signed URLs; those are delivery details generated for a ready snapshot.

Sharing — Share HTML (external-facing public URL)

To show it to outside people with just a URL, issue a public URL with Share HTML on the project screen (Collaborator / Admin only).

  • There is only one public URL per project. Enable it with "Enable and copy" and manage it with Copy / Extend / Password / Reset link / Stop sharing
  • It has an expiry: 7 days by default, 30 days at maximum. Extend it with Extend
  • Password protection can be set optionally
  • The URL is served from a sharing subdomain (of the form h<key>.html.aachat.work); Reset link (rotate) invalidates the old URL
  • Agents cannot issue a public URL. The decision to publish and the operation are performed by humans

Build a small report

Use an active Project and a Collaborator/Admin authoring role; the authoring Session must cover the Project. With aachat up running, save the following as aachat/projects/acme/customer-research/html/report.html, replacing the Project path with yours. Add its companion html/report.css. This example needs no backend or external script.

html
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Customer research</title>
  <link rel="stylesheet" href="report.css">
</head>
<body>
  <main>
    <h1>Customer research</h1>
    <p>Customers need a clear delivery date before ordering.</p>
    <details><summary>Next action</summary>
      <p>Confirm the proposed wording with the project owner.</p>
    </details>
  </main>
</body>
</html>

html/report.css:

css
body { margin: 0; font: 1rem/1.6 system-ui, sans-serif; color: #172033; }
main { max-width: 48rem; margin: auto; padding: 2rem; }
summary { cursor: pointer; font-weight: 600; }

Add <a href="report.html">Customer research</a> to the existing html/index.html hub without removing its other page links. For a single-report Project, you can instead save the report as html/index.html. CSS is relative to the HTML file: if you move the report into a subdirectory, adjust that relative path.

After sync and a successful latest build, open HTML → Pages → report.html. Expect the heading, a readable centered layout, and a Next action disclosure that expands when selected. A member can open the page without enabling a public share. To show a ready Media asset, use the canonical reference rules above; a local image filename is not proof it has been published.

Project HTML hosts static files. It does not start a server, provision a database connection, inject credentials, or grant a viewer the author's Project API permissions. Prepare a static data file if the report needs database results, and review that data before sharing.

Check updates and sharing failures

If the page is missing, check the Project path, authoring permission, file limits, sync, and the catalog diagnostic. If it is pending, source acceptance has happened before a usable new build. If failed, fix the reported path or Media reference and save again; an older successful snapshot is not proof the new source is visible.

Share HTML exposes the Project's built HTML surface, not just the page you selected. Review all files, data, scripts, and media dependencies before enabling it. Later successful builds update what the share serves. If a public reader cannot open it, inspect expiry, password, reset/stop state, Project status, and latest build state. Reset link invalidates the old URL; Stop sharing disables public access, but neither retracts copies a recipient already saved. See Sharing to choose a narrower document link.

Related pages

  • The full picture of deliverable surfaces (docs / media / html): projects
  • Publishing images, videos, and PDFs: media
  • Where the operations live in the WebUI: webui