# SharePoint /_html

> Author HTML for SharePoint, choose whether it lives in OneDrive/a document library or Site Pages, then save it as the signed-in user. Reading this guidance is anonymous; writing is authenticated.

## Choose where the HTML should live

SharePoint can present authored `.html` in two ways. Choose the destination before writing it; both destinations use the authoring contract below, while Site Pages also requires the creation sequence later in this document.

- **OneDrive or a document library:** Save a standalone .html file here to open it in the OneUp HTML viewer.
- **Site Pages:** Save the .html file in the current web’s designated Site Pages library when it should render with SharePoint site page chrome or may become the site homepage. This is a distinct publishing mechanism, not a file upload: use only the sitepages/htmlpages REST calls below. A drive/driveItem upload, createUploadSession, a generic connector file-upload action (e.g. WorkIQ), or any other document-library upload path does not create a Site Page — at best it places an unrelated file in a document library, and at worst leaves a zero-byte placeholder with no HTML content.

## The renderer

Your HTML renders inside a sandboxed iframe (`sandbox="allow-scripts"`) under a strict CSP that FAILS SILENTLY — non-compliant HTML renders blank or partially broken with no error.

## Content-Security-Policy applied to your HTML

```
default-src 'none';
script-src 'unsafe-inline' 'unsafe-eval';
style-src 'unsafe-inline';
img-src data: blob:;
font-src data: blob:;
media-src data: blob:;
connect-src 'none';
worker-src 'none';
object-src 'none';
base-uri 'none';
form-action 'none';
```

The wrapper iframe additionally applies `frame-src 'none'`.

## Non-negotiable rules

1. No caller-controlled external URLs: no <script src>, <link href>, <img src=https://…>, @import, url(https://…), or remote fonts. Curated libraries are the only exception: declare allowlisted library names without versions in a ka-lib-manifest; the host selects the currently supported version, verifies it, and injects it inline. Any supplied version is ignored.
2. Choose curated libraries by intent, even when the user does not name one: D3.js 7.9.0 for custom SVG/data visualizations, topojson-client 3.1.0 with world-countries-110m (world-atlas 2.0.2) or us-counties-10m (us-atlas 3.0.1) for maps, @floating-ui/core 1.7.3 or @floating-ui/dom 1.7.4 for anchored tooltips/popovers, and lucide 1.17.0 for SVG icons. FloatingUIDOM includes its core dependency; a separate core declaration is not required. Use topojson.feature to convert worldCountries110m.objects.countries/land or usCounties10m.objects.counties/states/nation to GeoJSON for d3.geoPath. Use inline or host-provided LiveData data, never d3.json/d3.csv or another network loader; d3.csvParse can parse supplied CSV text. Declare only used IDs in one ka-lib-manifest before all authored executable scripts, at most six entries total. Honor no-library/vanilla JavaScript/static-image preferences and avoid libraries for simple static pages or KPI/table-only dashboards.
3. All authored script must be inline <script> blocks. No module imports, no import(), no <script src>.
4. All styling must be inline <style> or style="…" attributes. No <link rel="stylesheet">.
5. Host theming is opt-in: when requested, add <meta name="ms-sp-host-theme" content="live"> to the head (output.html/create_file useSiteTheme:true does this). Use Fluent CSS variables such as var(--colorBrandBackground, #0078d4), var(--colorNeutralForeground1, #242424), var(--colorNeutralBackground1, #fff), and var(--fontFamily, "Segoe UI") with generated fallbacks. The containing host, including embed, supplies runtime-only tokens on open and explicit refresh; do not fetch the file-owning site theme, persist host values, redefine host tokens, or migrate ordinary files or legacy snapshots. Outside the viewer or without a host theme, generated styling remains.
6. No network APIs at runtime (fetch, XMLHttpRequest, WebSocket, sendBeacon, EventSource). For SharePoint file OR list data at view time, use the LiveData manifest pattern (a file item, or a kind:"list" item).
7. No storage primitives (localStorage, sessionStorage, indexedDB, document.cookie) — opaque-origin sandbox. For cross-reload state, set location.hash directly (e.g. location.hash = "#slide=3"); do NOT use history.pushState/replaceState — the sandboxed document’s base URL is inherited from the wrapper’s blob: origin, so any url argument throws SecurityError.
8. No top-level navigation, popups, forms submission, workers, or plugins. Sandbox is allow-scripts only; alert/confirm/prompt are no-ops.
9. Inline on*= handlers are supported (rewritten to nonced scripts) but are an XSS sink if they template non-author-controlled data — use addEventListener for computed/user/fetched data.
10. Save the file as UTF-8 with a BOM (the ODSP file-creation API does this automatically).

## Live SharePoint data (LiveData) - the only runtime data source

Runtime `fetch`/`XMLHttpRequest`/`WebSocket` are blocked by CSP. To show live SharePoint file content you
DECLARE the files in a manifest; the OneUp host prefetches each one SERVER-SIDE with the credentials of the
viewing user and injects the results as `window.__LD_RESULTS__` BEFORE any of your scripts run. Your script
reads that global - it never fetches.

### 1. Declare a manifest

```html
<script type="application/json" class="ka-livedata-manifest">
[{ "spItemUrl": "https://{host}/_api/v2.0/drives/{driveId}/items/{itemId}", "fileName": "data.csv" }]
</script>
```

Multiple manifest blocks are allowed; the host unions and de-dupes them by `spItemUrl`. Item fields:
- `spItemUrl` (string, REQUIRED): the driveItem URL of the file. It MUST contain `/drives/{driveId}/items/{itemId}`.
  The host reads ONLY driveId + itemId and re-issues the fetch against the viewer session - the URL host/origin
  is IGNORED (so a manifest cannot point at another tenant to leak the token).
- `fileName` (string, REQUIRED in practice): the file name WITH extension. The host picks the decoder from this
  extension. Omit it and the file is decoded as plain `text` - an `.xlsx` comes back unreadable and a `.csv` is
  not parsed as csv. ALWAYS include it.
- `filePath` (string, optional): server-relative path; used as an extension fallback when `fileName` is absent.
- `uniqueId` (string, optional): SharePoint item GUID, forwarded for attribution.
- `label` (string, optional): display label passed through to your code.

SharePoint LIST items (`kind:"list"`): instead of a file, declare a list. The host renders it server-side
(the same engine the Lists UI uses), flattens every column to a display string, and injects it as `format:"rows"`:
```html
<script type="application/json" class="ka-livedata-manifest">
[{ "kind": "list", "spItemUrl": "list:{webUrl}/{listId}", "webUrl": "https://{tenant}.sharepoint.com/sites/{site}",
   "listId": "{list-guid}", "listServerRelativeUrl": "/sites/{site}/Lists/{list}", "select": ["Title","Amount"] }]
</script>
```
- `kind` (string, REQUIRED for a list): `"list"`. Omit or `"file"` selects the file path above.
- `spItemUrl` (string, REQUIRED): a SYNTHETIC key `list:{webUrl}/{listId}` - the de-dupe id and `__LD_RESULTS__` key; never fetched.
- `webUrl` (string, REQUIRED): absolute web URL of the site; host-validated against the tenant allowlist before fetch.
- `listId` (string, REQUIRED): the list GUID.
- `listServerRelativeUrl` (string, optional): server-relative list URL; preferred fetch identity when known.
- `viewId` (string, optional): render a specific view’s columns. `select` (string[], optional): INTERNAL column
  names to fetch (they become the result `headers`). `top` (number, optional): row-count hint (clamped host-side).

How to get `listId` + INTERNAL column names (as the signed-in user). The site (web) URL is everything in the
list URL before `/Lists/` (e.g. `https://{tenant}.sharepoint.com/teams/{site}`). Then either API works:
- SharePoint REST (one hop from the site URL). List GUID + server-relative URL:
  `GET {webUrl}/_api/web/lists/getbytitle('{ListDisplayName}')?$select=Id&$expand=RootFolder` (read `Id` +
  `RootFolder/ServerRelativeUrl`). Columns/schema:
  `GET {webUrl}/_api/web/lists/getbytitle('{ListDisplayName}')/fields?$select=InternalName,Title,TypeAsString&$filter=Hidden eq false`.
  Use `InternalName` in the manifest `select` (it can differ from the display Title - e.g. a column titled "City"
  may have InternalName `Ciity`). Send header `Accept: application/json;odata=nometadata` for clean JSON. Docs:
  https://learn.microsoft.com/en-us/sharepoint/dev/sp-add-ins/working-with-lists-and-list-items-with-rest
- Microsoft Graph equivalent: `GET /sites/{hostname}:/{server-relative-path}?$select=id` (site id), then
  `GET /sites/{site-id}/lists/{list-id}/columns` (schema; `name` = internal name, `displayName` = title) and
  `GET /sites/{site-id}/lists/{list-id}/items?$expand=fields` (data). Docs:
  https://learn.microsoft.com/en-us/graph/api/list-list-columns?view=graph-rest-1.0

### 2. How to get the spItemUrl (it needs driveId + itemId)

As the signed-in user, resolve the file once (also read its real name for `fileName`):
- From a file or sharing URL: `GET /shares/{u!token}/driveItem?$select=id,name,file,parentReference` and read
  `parentReference.driveId` + `id` (and `name`/`file` for the extension). (u!token = `u!` + unpadded base64url
  of the URL: base64, strip `=`, `/`->`_`, `+`->`-`.)
- Or from Graph/Vroom by path: `GET /me/drive/root:/path/file.csv?$select=id,name,file,parentReference`.
Then build `https://{host}/_api/v2.0/drives/{driveId}/items/{itemId}` (or the
`https://graph.microsoft.com/v1.0/drives/{driveId}/items/{itemId}` equivalent). Only driveId + itemId are read.

Two gotchas when resolving:
- Set `fileName` from the RESOLVED name/extension, NOT from the sharing-URL prefix. A `:x:`/`:w:`/`:p:` link
  prefix indicates the Office app, not the file type (an `:x:` link is often a real `.csv`) - guessing the
  extension from it picks the wrong decoder.
- If you download the file to inspect it, `GET .../items/{itemId}/content` returns a 302 to a pre-authenticated
  URL; follow redirects (`fetch` does automatically; `curl` needs `-L`).

### 3. Read the injected results

Before your scripts run, the host defines this global (keyed by the EXACT spItemUrl string you declared):

```js
window.__LD_RESULTS__ = {
  "<spItemUrl>": {
    spItemUrl: "<same string you declared>",
    format:   "csv" | "text" | "xlsx-sheets" | "rows",  // "rows" = SharePoint list data (JSON {headers,rows})
    content:  "<decoded string>",               // present on SUCCESS (see per-format below)
    metadata: { fileName, extension },
    error:    "<message>",                       // present on FAILURE, instead of content
    errorCode:"invalid-request|parse-failed|fetch-failed|decode-failed|access-denied|not-found|protected",
    warning:  "<caution>"                        // optional; content still present (best-effort)
  }
}
```

Reading rules:
- If `window.__LD_RESULTS__` or your entry is missing, you are NOT inside the viewer (the page is also opened
  directly while authoring). Render a friendly placeholder; do not crash.
- If `entry.error` is set, show it. Access-denied is sometimes reported as `not-found`.
- Otherwise parse `entry.content` according to `entry.format`.

### 4. content per format
- Supported formats: text, csv, xlsx-sheets, rows.
- `csv`  -> the raw CSV text exactly as stored. Parse it yourself (split lines, split on commas, handle "quotes").
- `text` -> the raw file text.
- `xlsx-sheets` -> every sheet as text, each wrapped in a tag block, blocks separated by a blank line:

```
<sheet name="Sheet1">
a,b,c
1,2,3
</sheet>

<sheet name="Sheet2">
...
</sheet>
```

  Split on `<sheet name="...">` ... `</sheet>` blocks; the text between the tags is CSV (or the literal `(empty sheet)`).
- `rows` (SharePoint lists) -> `content` is a JSON string `{ "headers": string[], "rows": string[][] }`, already
  flattened to display strings host-side (headers are the INTERNAL column names). `JSON.parse(content)` - no CSV parsing.

### 5. Limits (fail-closed)
- Max 32 items per page (union of all manifests). Exceeding it drops ALL results (every fragment
  renders empty), so keep manifests small (typically 5 or fewer files).
- Max 50 MiB per item; an item with no Content-Length or over the cap is refused (errorCode fetch-failed).
- SharePoint list items: max 100,000 rows; a larger list is truncated to the cap and still renders with a non-blocking `warning`.
- Fetches bypass the HTTP cache, so a refresh always reflects the latest saved file.

### 6. Refresh (live updates)
- Post to the parent: `parent.postMessage({ type: 'ka-html-viewer-refresh' }, '*')`.
- Debounced to one accepted refresh per 5s (extra calls are silently dropped).
- On accept, the host re-prefetches and RE-LOADS your iframe, so your page simply runs again with fresh
  `window.__LD_RESULTS__`. There is NO inbound "updated" message - do not wait for one.

### 7. Safety
- LiveData content is UNTRUSTED: never inject it via `innerHTML` or into `on*=` handlers (XSS sink). Build DOM
  with `textContent`/`createElement`, or escape. (See the numbered rule about on*= handlers above.)
- Runtime network APIs stay blocked - LiveData is the ONLY data path. Never put secrets in the page.

### 8. Minimal working CSV dashboard

```html
<script type="application/json" class="ka-livedata-manifest">
[{ "spItemUrl": "https://contoso.sharepoint.com/_api/v2.0/drives/{driveId}/items/{itemId}", "fileName": "data.csv" }]
</script>
<div id="out">Loading live data...</div>
<script>
  // Derive the key from the injected results - do NOT duplicate the manifest spItemUrl as a string.
  var results = window.__LD_RESULTS__ || {};
  var KEY = Object.keys(results)[0]; // single-item manifest; for many, read the manifest <script> JSON
  var r = KEY ? results[KEY] : null;
  var out = document.getElementById("out");
  if (!r) { out.textContent = "Open this file in SharePoint to see live data."; }
  else if (r.error) { out.textContent = "Error: " + r.error; }
  else {
    var rows = r.content.trim().split(/\r?\n/).map(function (l) { return l.split(","); });
    var t = document.createElement("table");
    rows.forEach(function (cells, i) {
      var tr = document.createElement("tr");
      cells.forEach(function (c) { var cell = document.createElement(i ? "td" : "th"); cell.textContent = c; tr.appendChild(cell); });
      t.appendChild(tr);
    });
    out.textContent = ""; out.appendChild(t);
  }
  // live refresh (host debounces 5s): parent.postMessage({ type: "ka-html-viewer-refresh" }, "*")
</script>
```

## Curated external libraries

Declare exact names before your user scripts; never emit a library URL:

```html
<script type="application/json" class="ka-lib-manifest">
["chart.js", "mermaid"]
</script>
```

Available: `babylon` → `window.BABYLON`, `chart.js` → `window.Chart`, `d3` → `window.d3`, `topojson-client` → `window.topojson`, `world-countries-110m` → `window.worldCountries110m`, `us-counties-10m` → `window.usCounties10m`, `@floating-ui/core` → `window.FloatingUICore`, `@floating-ui/dom` → `window.FloatingUIDOM`, `lucide` → `window.lucide`, `mermaid` → `window.mermaid`, `react` → `window.React`, `window.ReactDOM`, `fluentui` → `window.FluentUI`, `window.React`, `window.ReactDOM`.
The host fetches first-party bytes, verifies pinned integrity, and injects them inline before user scripts. Unknown names are ignored; max 6 entries, 8 MiB each, 16 MiB total.

## Links

`<a href>` opens only for same-tenant SharePoint hosts, the current OneDrive page origin, or the external allowlist (microsoft.ghe.com, onedrive.cloud.microsoft, 1drv.ms); `javascript:`/`vbscript:`/`data:` hrefs are rejected.

## Publish (authenticated as the current user)

- Auth: delegated OAuth — scope `Files.ReadWrite` for the user’s own OneDrive, or `Sites.ReadWrite.All` for a SharePoint site library. Never fabricate a token.
- Before uploading, LIST the destination folder (…/children) to detect a name collision. For CREATE, inspect and disclose the destination’s existing audience because the new item inherits those permissions. For OVERWRITE, inspect and disclose the target item’s own existing audience, permissions, and sharing links because its identity, unique permissions, and existing anonymous or organization links remain in place for the replacement content. If an audience cannot be inspected, state that uncertainty. Tell the user CREATE vs OVERWRITE, then CONFIRM. Uploading creates no new sharing link or anonymous access.
- Self-check before publishing (top failure is "renders blank with no error"): NO caller-controlled external refs (<script src>, <link>, @import, url(https:)); curated libraries use ka-lib-manifest names only. NO fetch/XHR/WebSocket, render untrusted/LiveData data with textContent (not innerHTML), and every LiveData manifest item has spItemUrl AND fileName.
- Graph (primary): `PUT https://graph.microsoft.com/v1.0/me/drive/root:/Agent HTML/<name>.html:/content` (Content-Type: text/html; ≤ 4 MB simple upload, else upload session). graph.microsoft.com routes to whichever SPO farm holds the caller’s OneDrive — including dogfood rings like *.sharepoint-df.com — based on the token, so it just works.
- SharePoint site library: Graph `PUT https://graph.microsoft.com/v1.0/sites/{site-id}/drive/root:/Agent HTML/<name>.html:/content` or Vroom `PUT {siteUrl}/_api/v2.0/drive/root:/Agent HTML/<name>.html:/content` (scope `Sites.ReadWrite.All`; the site drive root is its default “Shared Documents” library, so keep the path root-relative).
- Publish by folder URL (fewest calls; any OneDrive/site/library): encode the destination folder URL as `u!`+base64url (strip `=`, `/`→`_`, `+`→`-`), `GET /shares/{u!token}/driveItem` → folder driveItem (`id` + `parentReference.driveId`), then `PUT /drives/{driveId}/items/{folderId}:/<name>.html:/content`. Graph base graph.microsoft.com/v1.0; Vroom base {host}/_api/v2.0.
- SharePoint API (Vroom) alternative for your OneDrive: `PUT https://{tenant}-my.sharepoint.com/_api/v2.0/me/drive/root:/Agent HTML/<name>.html:/content` — use when you already hold a SharePoint-audience token (SPFx/add-in/on-behalf-of) or want to target a specific SharePoint host directly.
- Get the URL: read `webUrl` from the driveItem response, then open `<webUrl>?web=1` — the `?web=1` renders it in the OneUp HTML viewer; the bare `webUrl` downloads the .html file. Stable across updates.
- Update: PUT the same path (or `/me/drive/items/{item-id}/content`) to overwrite; PATCH the item to rename/move.

## Create an HTML page in Site Pages

Use exactly these three ordered calls. They create the HTML Page, verify the exact returned identity and fresh version, and save the complete HTML as an author-visible draft. Do not use a drive/driveItem upload, a content PUT, createUploadSession, or a generic connector file-upload action (e.g. WorkIQ) to do this — those write into a document library, not Site Pages, do not run the save below, and can leave a zero-byte placeholder with no HTML content.

### 3 required calls

#### Create the HTML Page

Create through the supported Site Pages service and capture the exact filename, URL, file GUID, and item ID returned by SharePoint.

```http
POST <current-web-url>/_api/sitepages/pages

Headers:
Accept: application/json;odata=nometadata
Content-Type: application/json;odata=nometadata

Body:
{ "Name": "<requested-exact-.html-filename>", "ContentTypeId": "0x0101009D1CB255DA76424F860D91F20E6C411800EE3B4FE2C29A4DCDB55229ADEB3DBFE4" }
```
- This sanctioned creation path provisions the requested HTML Page content type while creating the file. Stop if it is unavailable; a transport failure before any response from the selected web is not this condition.
- Apply sharedGuidance.authentication, sharedGuidance.identityAndContentType, and sharedGuidance.saveOutcomes before continuing.

#### Verify the exact created page

Normalize the returned location, verify the exact file and list-item identity plus the HTML Page content-type prefix, and read a fresh top-level UIVersion.

```http
GET <current-web-url>/_api/web/GetFileByServerRelativePath(DecodedUrl=@filePath)?$select=UniqueId,ServerRelativeUrl,UIVersion,ListItemAllFields/Id,ListItemAllFields/ContentTypeId,ListItemAllFields/FileLeafRef&$expand=ListItemAllFields&@filePath=<encodeURIComponent-of-quoted-created-file-server-relative-url>

Headers:
Accept: application/json;odata=nometadata
```
- Run immediately before HtmlPage.Save.
- Apply sharedGuidance.locationAndOData and sharedGuidance.identityAndContentType; use only the verified item ID and fresh top-level file UIVersion in Save.

#### Save the final HTML as a draft

Save the complete BOM-prefixed document with the fresh version token, then report the successful result as an author-visible draft.

```http
POST <current-web-url>/_api/htmlpages/pages(<verified-item-id>)/save(currentVersion=<fresh-UIVersion>,generateNewVersion=true)

Headers:
Accept: application/json;odata=nometadata
Content-Type: text/html; charset=utf-8

Body:
Complete final UTF-8 HTML document bytes beginning with UTF-8 BOM bytes EF BB BF (max 10 MiB including the BOM).
```
- HtmlPage.Save updates the verified existing item; it does not create an item.
- Apply sharedGuidance.authentication and sharedGuidance.saveOutcomes. Preserve the successful <saved-UIVersion> for any later advanced operation.

### Shared creation safety

- Use the selected web’s absolute URL as <current-web-url> for every request. The lifecycle requires authentication accepted by that target SharePoint web; do not claim support for an external caller until its real token and tenant have been tested.
- For cookie authentication, obtain a current form digest from <current-web-url>/_api/contextinfo and send it as X-RequestDigest on every state-changing POST. OAuth bearer-token callers do not send a request digest.
- Prefer Path.DecodedUrl, then Url, as the create response’s decoded web-relative path. Do not call decodeURIComponent on either value. Strip only leading slashes and join it to the selected web’s decoded server-relative pathname with one slash. For example, web /sites/Team/Subweb plus /SitePages/Director's plan.html becomes /sites/Team/Subweb/SitePages/Director's plan.html.
- Use AbsoluteUrl only when neither decoded path field is present. Require it to begin with the exact selected web absolute URL plus a path separator, remove that prefix by string slicing rather than URL parsing, and treat the remainder as an already-decoded web-relative path. Stop on a prefix mismatch. Never pass decoded names such as Plan#1.html, Plan%20one.html, or Plan%.html through new URL or decodeURIComponent.
- Build @filePath exactly as encodeURIComponent(`'${serverRelativeUrl.replace(/'/g, "''")}'`): double embedded apostrophes, wrap the complete normalized path in single quotes, then pass that complete OData literal to encodeURIComponent. Never interpolate a raw path into the query string.
- Capture the create response’s Id, UniqueId, FileName, AbsoluteUrl, and Path.DecodedUrl (or Url). Require FileName to equal the requested exact .html filename.
- SharePoint may conflict-rename the page (for example requesting plan.html but receiving plan(2).html) instead of erroring. Treat a returned FileName/FileLeafRef that differs from the requested exact filename the same as any other verification failure: perform no mutation. Stop and report the exact returned Id, UniqueId, AbsoluteUrl, ServerRelativeUrl, and FileLeafRef; explicitly warn that the renamed item remains. Never save HTML into this or any other guessed/assumed item. Before recycling or deleting the conflict-created item, require explicit user confirmation that names that exact returned identity (UniqueId plus ListItemAllFields/Id). Never infer a cleanup target from the requested filename.
- Immediately before Save, read the normalized exact location and require UniqueId, ListItemAllFields/Id, ListItemAllFields/FileLeafRef, and normalized ServerRelativeUrl to match the create response. Treat Path.DecodedUrl, Url, and ServerRelativeUrl as decoded paths; do not decode them again. Convert backslashes to forward slashes, collapse duplicate slashes, and require one leading slash; never lowercase names or resolve traversal segments.
- Require ListItemAllFields/ContentTypeId to equal or start with 0x0101009D1CB255DA76424F860D91F20E6C411800EE3B4FE2C29A4DCDB55229ADEB3DBFE4; child content types are valid, unrelated content types are not.
- Before creation, require an exact .html filename, reject path traversal, and send the complete filename including its final .html extension as Name. This preserves dotted basenames: release.v2.html, report.2026.09.html, and index.html must be sent unchanged. Require the final UTF-8 HTML including its BOM to be no larger than 10 MiB.
- Use only the verified ListItemAllFields/Id as <verified-item-id> and the immediately read top-level file UIVersion as <fresh-UIVersion>. Never use currentVersion=-1.
- Prefix the complete final document with U+FEFF so the body begins with UTF-8 BOM bytes EF BB BF; count those three bytes toward the 10 MiB limit.
- After Save is dispatched, treat HTTP 409 as a concurrency conflict and an unavailable response as an unknown outcome. Never automatically recycle, delete, or retry after either result; report the exact page URL and IDs because another session or a successful hidden write may exist.
- If Save rejects the content type or the HTML Pages API is unavailable, stop and report the failure. Do not mutate the content type, provision a library, use a generic upload fallback, or add an internal retry loop. A connector or transport failure prior to a response from the selected web is not this condition; see creationTransportRecovery.
- On success, require HtmlPageSaveResult.UIVersion and preserve it as <saved-UIVersion>. The saved result is an author-visible draft until a separately requested publication succeeds, and approval completes when required.

### If a transport or connector fails

Distinguish transport/tool failure from target API failure. A connector diagnostic that it never dispatched the request or never received any response from the selected web (e.g. its own executed:false, a pre-routing/pre-dispatch failure) is evidence about that connector only. A status such as HTTP 404, accessDenied, a tenant-routing failure, missing content-upload support, an auth-context mismatch, or CLI/device-code auth blocked by Conditional Access — from any connector (Graph, Power Platform, WorkIQ, or another connector) — is NOT by itself evidence of a transport failure: if the connector actually dispatched the request and that status came back from the selected web, it is an endpoint-produced result and must be reported as-is, the same as any other stop condition — never discarded or treated as connector-only to justify switching transport. Confirm the connector reports it never dispatched or never got a response before treating a status as connector-only.

Before dispatching the Create call above (never after), you may select at most one already-authorized alternate transport and use it once for a single harmless read-only check. If CLI/device-code/connector auth is blocked or lacks delegated SharePoint REST access, but an authenticated browser session can open the target web, same-origin SharePoint REST through that browser tab is a valid transport — use the browser only to supply the authenticated session (cookies) and a form digest (`/_api/contextinfo` → `X-RequestDigest` for later POSTs) for the same REST calls, never to manually upload the file or run address-bar/dev-console JavaScript workarounds. A file-upload-only helper (drive/driveItem upload, createUploadSession, WorkIQ-style upload) cannot issue these REST calls and is never a valid alternate transport here. Switch transport only, never destination — still use the three calls above, and never fall back to OneDrive or a document library. If no compliant transport can call SharePoint REST, stop and report that transport/auth is unavailable. Once Create or Save has actually been dispatched on any transport, do not switch transport or retry it; report an inconclusive result as unknown, not failed.

For publication, approval, homepage changes, or deletion, resolve `help.json` from the same versioned artifact directory as this `llms.txt` and follow its canonical `sitePages` contract.

## Agent skill

Install the open agent skill (authoring contract + publish workflow + CSP-compliant templates): https://github.com/SharePoint/sharepoint-html

Claude Code, Codex, or Copilot CLI:
```
curl -fsSL https://raw.githubusercontent.com/SharePoint/sharepoint-html/main/install.sh | sh
```
Or via the cross-agent Agent Skills CLI (installs to all detected agents):
```
npx skills add SharePoint/sharepoint-html
```

## Source of truth

- CSP + sandbox: `odsp-common/high-value-components/html-viewer/src/security/HtmlViewerSecurity.ts`
- LiveData item cap: `odsp-common/high-value-components/html-viewer/src/liveData/LiveDataManifest.ts`
- Per-item byte cap + formats: `odsp-common/high-value-components/html-viewer/src/handlers/useGetDataHandler.ts`
- Refresh debounce: `odsp-common/high-value-components/html-viewer/src/handlers/useRefreshHandler.ts`
- External link allowlist: `odsp-common/high-value-components/html-viewer/src/handlers/linkSafety.ts`
- External libraries: `odsp-common/high-value-components/html-viewer/src/externalLibraries/ExternalLibraries.ts`
- SharePoint list live data: `odsp-next/app-cores/oneup-lightspeed/src/viewers/htmlViewer/fetchListRowsForOneUp.ts`

_This spec mirrors the OneUp HTML viewer source listed above and is the authoritative, current contract._