Hosting & integrations

Release 0.1.0-beta.1 · API 1.0-beta · Source-available license 1.0

Static hosting

The release runs on a static HTTP(S) host. Retain the versioned directory and its notices. Keep your original design permissions separate from software licensing. Public runtime files and design URLs remain retrievable by visitors; a read-only interface is not access control.

Use the complete ZIP, or the immutable browser files under:

https://wayri.github.io/assets/lib/kicad-webview/releases/0.1.0-beta.1/

Serve JavaScript with a JavaScript MIME type and JSON manifests as JSON. Modules require an HTTP(S) context with permitted origins. A relative design URL is resolved against the supplied loading base; the iframe uses its own page as that base. For readable examples see quick start.

Hosted, local and GitHub sources

Viewer.load accepts a supported drawing URL, project manifest, supported repository URL or manifest object. A hosted .kicad_pro alone is not a list of its related files: provide a manifest. A supported GitHub repository/tree/project URL can discover files; the loader resolves the selected revision to an immutable commit and rejects truncated listings rather than silently omitting files.

For branches containing /, supply an explicit matching ref. Public GitHub API availability and rate limits still apply. The library does not obtain private-repository tokens. A public URL is not permission to redistribute its design.

Local browser files use loadFiles; bounded ZIP bytes use loadArchive. They are read in browser memory without uploading the design through these library methods. Local model paths need matching supplied assets. See the viewer loading reference and archive utilities.

Project manifest

List the project’s supported drawings and models explicitly. Relative URLs resolve against the hosted manifest URL. Paths identify files within the project; they are not filesystem access.

{
  "entry": "board.kicad_pcb",
  "files": [
    { "path": "board.kicad_pcb", "url": "./board.kicad_pcb" },
    { "path": "board.kicad_sch", "url": "./board.kicad_sch" },
    { "path": "models/connector.glb", "url": "./models/connector.glb" }
  ]
}

The source files must actually exist at those URLs, and the board’s saved model reference must resolve to the supplied model path. Keep child schematics in the manifest so project navigation can resolve them. A manifest’s explicit external URL remains external; a pinned GitHub parent does not make arbitrary external URLs immutable.

Iframe parameters

The versioned embed page supports:

file, ref, theme and inspection behavior are applied by the KiCad branch of this embed controller. Do not assume the Altium adapter implements the same options. This is a URL-configured viewer, not a cross-origin postMessage control API.

Release input limits

These are hard guards in the release, not recommended target project sizes. Smaller projects are more comfortable on phones and in constrained host applications.

ZIP reading supports stored and deflate entries with validation and CRC checks. ZIP64, encryption, multi-disk archives, nested archives, symlinks/special entries, unsafe paths and conflicting names are rejected. Deflate requires a browser with DecompressionStream('deflate-raw'); unpack supported files locally if unavailable. Optional limits may lower the ZIP caps, not raise them.

Additional geometry, hierarchy, virtual-control, analysis and export bounds are documented in the relevant API sections. A load that fits a byte cap can still exceed a renderer’s supported feature or geometry scope.

CORS, CSP and privacy

• Cross-origin design files, ES modules and exporter asset fetches need appropriate CORS responses. The viewer cannot bypass a server’s access policy. Prefer approved same-origin hosting for private work.
• Hosted loading defaults to credentials: 'omit'; the supported explicit alternative is same-origin, not cross-origin credential forwarding. Do not place tokens, passwords or signed/private URLs in public embed or view links.
• Configure a content security policy for the entry points and features you use. Dynamic styles, WebGL, optional blob workers and chosen source origins must be considered. Test a restrictive policy with the actual viewer instead of copying a blanket policy from a different host.
• To allow embedding by another application, frame-ancestors must be an HTTP response header. A meta tag does not enable it. Do not weaken unrelated pages or make a private design public to resolve an iframe failure.
• The self-contained HTML output uses a separate policy with connect-src 'none'. It contains the design bytes. Its lack of external fetches does not make sharing a private design safe.
• No file-selection upload is needed for local inspection. Your host page, analytics, extensions or application policies remain outside the library’s own loading contract.

Mobile and host applications

Give the viewer width:100%, a real responsive height and a host viewport meta tag that allows user zoom. The renderer adapts to its container, including a narrow iframe on a desktop. Controls and scrollable panels are bounded within that embed. See touch controls.

The release records responsive browser checks. Those checks do not establish physical iOS/Android gesture acceptance or compatibility with every app’s embedded browser. Uploaded standalone HTML is a snapshot and must be regenerated to change the bundled viewer.

The retired hosted preview service is not a dependency of the bundled HTML. No Forge login, app installation or platform account connection is needed to use the static release on this site.