@aperture-browser/session-element 0.0.0-init.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Taras Fomin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# @aperture-browser/session-element
+
+Custom elements that embed a live [Aperture](https://github.com/tarik02/aperture) browser session in any page. They render into Shadow DOM, so the page's styles and the session's never mix, and bundle React and everything else they need.
+
+- `<aperture-session>`: the session with its UI: tabs, toolbar and menus.
+- `<aperture-session-view>`: the session alone, for pages that build their own controls. It skips the UI kit and stylesheet, so it is much smaller.
+
+## `<aperture-session>`
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@aperture-browser/session-element/dist/aperture-session.js"></script>
+
+<aperture-session
+  base-url="https://aperture.example"
+  token="apv_…"
+  style="display: block; height: 600px"
+></aperture-session>
+```
+
+Or from a bundler: `import "@aperture-browser/session-element";`.
+
+Attributes:
+
+- `token`: a share link's editor (`ape_…`) or viewer (`apv_…`) token; the element grants exactly what the link grants.
+- `base-url`: the Aperture instance, when it is not the page's own origin. The instance must list your origin in `embed_allowed_origins`.
+- `hide`: parts of the UI to leave out, separated by spaces: `tabs`, `navigation` (back, forward, reload), `address-bar`, `presence`, `drawing`, `menus`, `status-badge`, `toaster`.
+
+The `features` property takes the same switches as the React component's `features` prop, e.g. `element.features = { tabs: false, addressBar: false }`. It is applied on top of `hide`.
+- `theme`: `light`, `dark` or `system` (the default).
+
+The element fills the size you give it. It uses the page's font; set `--aperture-font-sans` and `--aperture-font-mono` (used for URLs) on the element to pick others. It adds one `<style>` to the page for its CSS custom property registrations, which browsers ignore inside shadow roots.
+
+## `<aperture-session-view>`
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@aperture-browser/session-element/dist/aperture-session-view.js"></script>
+
+<aperture-session-view id="session" base-url="https://aperture.example" token="ape_…"></aperture-session-view>
+
+<script type="module">
+  const session = document.getElementById("session");
+  session.addEventListener("aperture-change", ({ detail }) => {
+    console.log(detail.status, detail.tabs, detail.activeTabId);
+  });
+  await session.whenConnected();
+  await session.navigate("https://example.com");
+</script>
+```
+
+Or from a bundler: `import "@aperture-browser/session-element/headless";`.
+
+It takes the `token` and `base-url` attributes and shows the active tab, forwarding input to it.
+
+- `snapshot` holds the current state: `status` (`loading`, `ready`, `invalid`, `expired` or `unavailable`), `role`, `connection`, `tabs` (`id`, `title`, `url`, `loading`) and `activeTabId`. The `aperture-change` event carries each new snapshot.
+- Methods: `navigate(url)`, `back()`, `forward()`, `reload()`, `stop()`, `openTab(url?)`, `closeTab(id)`, `activateTab(id)`. They act on the active tab where it applies and return a promise that resolves once Aperture has carried the command out; `openTab` resolves with the new tab's id. The promise rejects with an `Error` (`_tag` `LiveSessionError`) whose `message` says why: the session is not connected yet, or Aperture refused the command, for example a viewer token trying to navigate.
+- `whenConnected()` resolves with the snapshot once the session is connected, and rejects if the token turns out invalid, expired or unavailable.
+- `reconnect()` drops the connection and opens it again.
+- The `aperture-notice` event carries errors and confirmations (`level`, `message`) that `<aperture-session>` would show as toasts.
+
+Both elements load a shared module next to them, so a page that uses both loads React and the session core once.
+
+React apps that want to share their own React copy can use [`@aperture-browser/session-react`](https://www.npmjs.com/package/@aperture-browser/session-react) instead, which has the same full and headless split.

package/dist/aperture-session-view.js

@@ -0,0 +1,5 @@
+import{C as e,D as t,T as n,g as r,n as i,o as a,r as o,s,t as c}from"./aperture-t-Xm6-Va.js";var l=t(n(),1),u=e(),d=a(),f={status:`loading`,role:null,connection:`idle`,tabs:[],activeTabId:null},p=`
+:host { display: block; position: relative; overflow: hidden; }
+:host([hidden]) { display: none; }
+.mount { display: flex; height: 100%; }
+`;function m({token:e,onControl:t,onSnapshot:n,onNotice:r}){let{status:i,share:a,control:s}=c({token:e,onNotice:r}),u=(0,l.useMemo)(()=>({status:i,role:a?.role??null,connection:s.phase,tabs:s.targets.map(({id:e,title:t,url:n,loading:r})=>({id:e,title:t,url:n,loading:r})),activeTabId:s.activeTargetId}),[s.activeTargetId,s.phase,s.targets,a,i]);return(0,l.useEffect)(()=>t(s)),(0,l.useEffect)(()=>n(u),[n,u]),i===`ready`?(0,d.jsx)(o,{control:s}):null}var h=class extends HTMLElement{static observedAttributes=[`token`,`base-url`];#e=null;#t=null;#n=f;get snapshot(){return this.#n}navigate(e){return this.#i(t=>t.navigate(e))}back(){return this.#i(e=>e.historyBack())}forward(){return this.#i(e=>e.historyForward())}reload(){return this.#i(e=>e.reload())}stop(){return this.#i(e=>e.stopLoading())}openTab(e){return this.#i(t=>t.createTarget(e))}closeTab(e){return this.#i(t=>t.closeTarget(e))}activateTab(e){return this.#i(t=>t.activateTarget(e)).then(async()=>{await this.#r(t=>t.activeTabId===e)})}reconnect(){this.#t?.reconnect()}whenConnected(){return this.#r(e=>e.connection===`connected`)}#r(e){return new Promise((t,n)=>{let r=()=>{let i=this.#n;if(e(i))t(i);else if(i.status===`invalid`||i.status===`expired`||i.status===`unavailable`)n(new s({message:`the session is ${i.status}`}));else return;this.removeEventListener(`aperture-change`,r)};this.addEventListener(`aperture-change`,r),r()})}#i(e){let t=this.#t;return t?r(e(t.commands)):Promise.reject(new s({message:`the session is not connected`}))}connectedCallback(){let e=this.shadowRoot??this.attachShadow({mode:`open`});e.replaceChildren();let t=document.createElement(`style`);t.textContent=p;let n=document.createElement(`div`);n.className=`mount`,e.append(t,n),this.#e=(0,u.createRoot)(n),this.#c()}disconnectedCallback(){this.#e?.unmount(),this.#e=null,this.#t=null}attributeChangedCallback(){this.#c()}#a=e=>{this.#t=e};#o=e=>{JSON.stringify(e)!==JSON.stringify(this.#n)&&(this.#n=e,this.dispatchEvent(new CustomEvent(`aperture-change`,{detail:e})))};#s=e=>{this.dispatchEvent(new CustomEvent(`aperture-notice`,{detail:e}))};#c(){let e=this.getAttribute(`token`),t=this.getAttribute(`base-url`)??void 0;this.#e?.render(e?(0,d.jsx)(i,{baseUrl:t,children:(0,d.jsx)(m,{token:e,onControl:this.#a,onSnapshot:this.#o,onNotice:this.#s})},t??``):null)}};customElements.get(`aperture-session-view`)||customElements.define(`aperture-session-view`,h);export{h as ApertureSessionViewElement};