arcane-os 0.1.0-dev.5 → 0.1.1

package/browser-runtime/dependencies/strong-type/licence

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Brandon Nozaki Miller
+
+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/browser-runtime/dependencies/strong-type/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "strong-type",
+  "version": "2.0.0",
+  "type": "module",
+  "description": "Dependency-free native ESM type enforcement for JavaScript values, objects, classes, browsers, and Node.",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./index.js": "./index.js",
+    "./node": "./node.js",
+    "./node.js": "./node.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "node.js",
+    "assets/strong-type-header.png",
+    "README.md",
+    "licence"
+  ],
+  "sideEffects": false,
+  "directories": {
+    "example": "example"
+  },
+  "engines": {
+    "node": ">=12.21.0"
+  },
+  "scripts": {
+    "test": "node scripts/test.js",
+    "test:core": "node scripts/test.js core",
+    "test:node": "node scripts/test.js node",
+    "test:docs": "node scripts/test.js docs",
+    "test:legacy": "node scripts/test.js legacy",
+    "coverage": "node --test --experimental-test-coverage --test-coverage-include=index.js --test-coverage-include=node.js --test-coverage-lines=95 --test-coverage-branches=90 --test-coverage-functions=95 test/CI.js test/node.js test/docs.js",
+    "start": "node scripts/serve.js",
+    "nodeExample": "node ./example/node/typecheck.js",
+    "check": "npm test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RIAEvangelist/strong-type.git"
+  },
+  "keywords": [
+    "strong",
+    "type",
+    "validation",
+    "validate",
+    "check",
+    "checking",
+    "esm",
+    "isomorphic",
+    "browser",
+    "node"
+  ],
+  "author": "Roshi _ _",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/RIAEvangelist/strong-type/issues"
+  },
+  "homepage": "https://riaevangelist.github.io/strong-type/"
+}

package/browser-runtime/dom-event-instrumentation.mjs

@@ -0,0 +1,594 @@
+export const DOM_INTERACTION_EVENT='arcane.dom.interaction';
+export const DOM_MUTATION_EVENT='arcane.dom.mutation';
+export const DOM_OBSERVATION_STARTED_EVENT='arcane.dom.observation.started';
+export const DOM_OBSERVATION_STOPPED_EVENT='arcane.dom.observation.stopped';
+
+export const DEFAULT_DOM_EVENT_TYPES=Object.freeze([
+    'auxclick','beforeinput','blur','change','click','compositionend',
+    'compositionstart','compositionupdate','contextmenu','copy','cut','dblclick',
+    'drag','dragend','dragenter','dragleave','dragover','dragstart','drop','focus',
+    'focusin','focusout','input','keydown','keypress','keyup','paste','pointercancel',
+    'pointerdown','pointerenter','pointerleave','pointermove','pointerout','pointerover',
+    'pointerup','reset','scroll','selectionchange','submit','touchcancel','touchend',
+    'touchmove','touchstart','wheel'
+]);
+
+const EVENT_FIELDS=Object.freeze([
+    'altKey','button','buttons','charCode','clientX','clientY','code','ctrlKey','data',
+    'deltaMode','deltaX','deltaY','deltaZ','detail','inputType','key','keyCode',
+    'location','metaKey','movementX','movementY','offsetX','offsetY','pageX','pageY',
+    'pointerId','pointerType','repeat','screenX','screenY','shiftKey','which'
+]);
+
+const TEXT_ENTRY_EVENT_PATTERN=/^(?:beforeinput|composition(?:end|start|update)|input|key(?:down|press|up))$/u;
+const LEGACY_CHARACTER_CODE_PATTERN=/^(?:charCode|keyCode|which)$/u;
+const URL_IDENTIFIER_PATTERN=/\b(?:blob|data|file|ftp|ftps|http|https|ws|wss):/iu;
+const URL_ATTRIBUTE_PATTERN=/^(?:action|cite|data|formaction|href|poster|src|srcset)$/iu;
+const SENSITIVE_ATTRIBUTE_PATTERN=/(?:authorization|cookie|credential|password|secret|session|srcdoc|style|token|value|api[-_]?key)/iu;
+
+function boundedString(value,maximum){
+    const text=String(value??'');
+    return text.length<=maximum?text:`${text.slice(0,maximum)}…`;
+}
+
+function cssEscape(value){
+    if(typeof globalThis.CSS?.escape==='function')return globalThis.CSS.escape(value);
+    return String(value).replaceAll(/[^a-zA-Z0-9_-]/gu,character=>`\\${character.codePointAt(0).toString(16)} `);
+}
+
+function readAttribute(target,name){
+    try{
+        return typeof target?.getAttribute==='function'?target.getAttribute(name):null;
+    }catch{
+        return null;
+    }
+}
+
+function hasAttribute(target,name){
+    try{
+        return typeof target?.hasAttribute==='function'&&target.hasAttribute(name);
+    }catch{
+        return false;
+    }
+}
+
+function elementName(target){
+    return String(target?.localName??target?.tagName??'element').toLowerCase();
+}
+
+function siblingIndex(target){
+    const siblings=target?.parentElement?.children;
+    if(!siblings)return null;
+    const name=elementName(target);
+    let index=0;
+    for(const sibling of siblings){
+        if(elementName(sibling)!==name)continue;
+        index+=1;
+        if(sibling===target)return index;
+    }
+    return null;
+}
+
+function selectorSegment(target){
+    const id=String(target?.id??readAttribute(target,'id')??'');
+    if(id){
+        return URL_IDENTIFIER_PATTERN.test(id)?`${elementName(target)}[id]`:`#${cssEscape(id)}`;
+    }
+    for(const attribute of ['data-arcane-id','data-testid']){
+        const value=readAttribute(target,attribute);
+        if(value){
+            return URL_IDENTIFIER_PATTERN.test(value)
+                ?`[${attribute}]`
+                :`[${attribute}="${cssEscape(value)}"]`;
+        }
+    }
+    const name=elementName(target);
+    const index=siblingIndex(target);
+    return index===null?name:`${name}:nth-of-type(${index})`;
+}
+
+export function domSelector(target,root){
+    if(!target||typeof target!=='object')return null;
+    if(target.nodeType===9)return ':document';
+    if(target.nodeType===11)return ':shadow-root';
+    if(target.nodeType===3)return domSelector(target.parentElement??target.parentNode,root);
+    if(target.nodeType!==1&&target.localName===undefined&&target.tagName===undefined)return null;
+
+    const groups=[];
+    let segments=[];
+    let current=target;
+    const visited=new Set();
+    while(current&&current!==root&&!visited.has(current)){
+        visited.add(current);
+        segments.unshift(selectorSegment(current));
+        const hasId=String(current?.id??readAttribute(current,'id')??'')!=='';
+        if(hasId){
+            let currentRoot=null;
+            try{currentRoot=current.getRootNode?.()??null;}catch{}
+            if(currentRoot?.host){
+                groups.unshift(segments.join(' > '));
+                segments=[];
+                current=currentRoot.host;
+                continue;
+            }
+            break;
+        }
+        if(current.parentElement){
+            current=current.parentElement;
+            continue;
+        }
+        let currentRoot=null;
+        try{currentRoot=current.getRootNode?.()??null;}catch{}
+        if(currentRoot?.host){
+            groups.unshift(segments.join(' > '));
+            segments=[];
+            current=currentRoot.host;
+            continue;
+        }
+        break;
+    }
+    if(segments.length)groups.unshift(segments.join(' > '));
+    return groups.join(' >>> ')||selectorSegment(target);
+}
+
+function privateElement(target){
+    let current=target?.nodeType===3?target.parentElement??target.parentNode:target;
+    const visited=new Set();
+    while(current&&typeof current==='object'&&!visited.has(current)){
+        visited.add(current);
+        const type=String(current.type??readAttribute(current,'type')??'').toLowerCase();
+        const autocomplete=String(readAttribute(current,'autocomplete')??'').toLowerCase();
+        if(type==='password'||hasAttribute(current,'data-arcane-private')
+            ||autocomplete.includes('password')){
+            return true;
+        }
+        if(current.parentElement){
+            current=current.parentElement;
+            continue;
+        }
+        let currentRoot=null;
+        try{currentRoot=current.getRootNode?.()??null;}catch{}
+        current=currentRoot?.host??null;
+    }
+    return false;
+}
+
+export function describeDOMTarget(target,root){
+    if(!target||typeof target!=='object')return null;
+    if(target.nodeType===9){
+        return Object.freeze({kind:'document',selector:':document'});
+    }
+    if(target.nodeType===11){
+        return Object.freeze({
+            kind:'shadow-root',
+            selector:domSelector(target.host,root),
+            host:target.host?describeDOMTarget(target.host,root):null
+        });
+    }
+    if(target.nodeType===3){
+        return Object.freeze({
+            kind:'text',
+            selector:domSelector(target,root),
+            private:privateElement(target)
+        });
+    }
+    if(target.nodeType!==1&&target.localName===undefined&&target.tagName===undefined){
+        return Object.freeze({kind:target===globalThis?'global':'event-target',selector:null});
+    }
+    return Object.freeze({
+        kind:'element',
+        selector:domSelector(target,root),
+        tagName:elementName(target),
+        id:String(target.id??readAttribute(target,'id')??'')||null,
+        role:readAttribute(target,'role'),
+        name:readAttribute(target,'name'),
+        type:String(target.type??readAttribute(target,'type')??'')||null,
+        private:privateElement(target)
+    });
+}
+
+function targetValue(target,{captureInputValues,maxValueLength}){
+    if(!captureInputValues||!target||typeof target!=='object')return undefined;
+    if(privateElement(target))return '[REDACTED]';
+    const type=String(target.type??'').toLowerCase();
+    if(type==='checkbox'||type==='radio')return Boolean(target.checked);
+    if(type==='file'){
+        return Array.from(target.files??[],file=>({name:String(file?.name??''),size:Number(file?.size??0)}));
+    }
+    if(!('value' in target))return undefined;
+    const value=String(target.value??'');
+    if(value.length<=maxValueLength)return value;
+    return `${value.slice(0,maxValueLength)}…`;
+}
+
+function safeEventDetail(field,value,{captureEventDetails,maxValueLength},isPrivate,eventType){
+    if(isPrivate&&(field==='code'||field==='data'||field==='detail'||field==='key')){
+        return '[REDACTED]';
+    }
+    if(field==='data'||field==='detail'){
+        if(!captureEventDetails)return value===null?null:'[REDACTED]';
+    }
+    if(field==='key'||field==='code'){
+        const text=String(value??'');
+        const sensitive=TEXT_ENTRY_EVENT_PATTERN.test(eventType)
+            &&(field==='code'||text.length===1||text==='Unidentified');
+        if(sensitive&&!captureEventDetails)return '[REDACTED]';
+    }
+    if(LEGACY_CHARACTER_CODE_PATTERN.test(field)
+        &&(isPrivate||(TEXT_ENTRY_EVENT_PATTERN.test(eventType)&&!captureEventDetails))){
+        return '[REDACTED]';
+    }
+    if(typeof value==='string')return boundedString(value,maxValueLength);
+    if(value===null||typeof value==='number'||typeof value==='boolean')return value;
+    return captureEventDetails?'[UNSERIALIZED EVENT DETAIL]':'[REDACTED]';
+}
+
+function interactionRecord(event,root,options){
+    const path=typeof event?.composedPath==='function'?event.composedPath():[event?.target];
+    const target=path.find(item=>item&&typeof item==='object')??event?.target??null;
+    const isPrivate=privateElement(target);
+    const eventType=String(event?.type??'');
+    const details={};
+    for(const field of EVENT_FIELDS){
+        let value;
+        try{value=event?.[field];}catch{continue;}
+        if(value!==undefined&&typeof value!=='function'){
+            details[field]=safeEventDetail(field,value,options,isPrivate,eventType);
+        }
+    }
+    const value=targetValue(target,options);
+    return {
+        eventType,
+        target:describeDOMTarget(target,root),
+        path:path.map(item=>describeDOMTarget(item,root)).filter(Boolean),
+        bubbles:Boolean(event?.bubbles),
+        cancelable:Boolean(event?.cancelable),
+        composed:Boolean(event?.composed),
+        defaultPrevented:Boolean(event?.defaultPrevented),
+        trusted:Boolean(event?.isTrusted),
+        ...(Object.keys(details).length?{details}:{}),
+        ...(value===undefined?{}:{value})
+    };
+}
+
+function serializeNode(node,root,{captureNodeMarkup,maxSerializedNodeLength},privateContext=false){
+    const descriptor=describeDOMTarget(node,root);
+    if(privateContext||privateElement(node)){
+        return {target:descriptor,content:'[REDACTED]',truncated:false};
+    }
+    if(!captureNodeMarkup)return {target:descriptor,content:'[CONTENT OMITTED]',truncated:false};
+    let content='';
+    if(node?.nodeType===3||node?.nodeType===8)content=String(node.data??node.textContent??'');
+    else content=String(node?.outerHTML??node?.textContent??'');
+    const truncated=content.length>maxSerializedNodeLength;
+    return {
+        target:descriptor,
+        content:truncated?`${content.slice(0,maxSerializedNodeLength)}…`:content,
+        truncated
+    };
+}
+
+function attributeValue(value,attributeName,target,options){
+    if(value===null||value===undefined)return null;
+    if(privateElement(target)||SENSITIVE_ATTRIBUTE_PATTERN.test(attributeName))return '[REDACTED]';
+    if(URL_ATTRIBUTE_PATTERN.test(attributeName))return '[REDACTED URL]';
+    return boundedString(value,options.maxValueLength);
+}
+
+function mutationRecord(record,root,options){
+    const target=describeDOMTarget(record?.target,root);
+    if(record?.type==='attributes'){
+        const attributeName=String(record.attributeName??'');
+        const current=readAttribute(record.target,attributeName);
+        return {
+            mutationType:'attributes',target,attributeName,
+            namespace:record.attributeNamespace??null,
+            before:attributeValue(record.oldValue,attributeName,record.target,options),
+            after:attributeValue(current,attributeName,record.target,options)
+        };
+    }
+    if(record?.type==='characterData'){
+        const redacted=privateElement(record.target)||!options.captureNodeMarkup;
+        return {
+            mutationType:'characterData',target,
+            before:redacted?'[REDACTED]':record.oldValue??null,
+            after:redacted?'[REDACTED]':String(record.target?.data??record.target?.textContent??'')
+        };
+    }
+    const privateContext=privateElement(record?.target);
+    return {
+        mutationType:'childList',target,
+        previousSibling:describeDOMTarget(record?.previousSibling,root),
+        nextSibling:describeDOMTarget(record?.nextSibling,root),
+        added:Array.from(
+            record?.addedNodes??[],node=>serializeNode(node,root,options,privateContext)
+        ),
+        removed:Array.from(
+            record?.removedNodes??[],node=>serializeNode(node,root,options,privateContext)
+        )
+    };
+}
+
+function rootDescription(root,{captureNodeMarkup=false,maxValueLength=10_000}={}){
+    if(root?.nodeType===9){
+        const title=String(root.title??'');
+        return {
+            kind:'document',
+            url:root.location?.href?'[REDACTED URL]':null,
+            title:title?(captureNodeMarkup?boundedString(title,maxValueLength):'[CONTENT OMITTED]'):null,
+            root:describeDOMTarget(root.documentElement,root)
+        };
+    }
+    return describeDOMTarget(root,root);
+}
+
+function collectOpenShadowRoots(root){
+    const roots=[];
+    const candidates=[];
+    try{
+        if(typeof root?.querySelectorAll==='function')candidates.push(...root.querySelectorAll('*'));
+    }catch{}
+    for(const candidate of candidates){
+        if(candidate?.shadowRoot)roots.push(candidate.shadowRoot,...collectOpenShadowRoots(candidate.shadowRoot));
+    }
+    return roots;
+}
+
+export function createDOMInstrumentation({
+    eventManager,
+    root=globalThis.document,
+    eventTypes=DEFAULT_DOM_EVENT_TYPES,
+    MutationObserver:MutationObserverImpl=globalThis.MutationObserver,
+    captureEventDetails=false,
+    captureInputValues=false,
+    captureNodeMarkup=false,
+    captureMutations=true,
+    maxValueLength=10_000,
+    maxSerializedNodeLength=100_000,
+    observeOpenShadowRoots=true
+}={}){
+    if(!eventManager||typeof eventManager.emit!=='function'){
+        throw new TypeError('DOM instrumentation requires an event manager.');
+    }
+    if(!root||typeof root.addEventListener!=='function'||typeof root.removeEventListener!=='function'){
+        throw new TypeError('DOM instrumentation requires an EventTarget-compatible root.');
+    }
+    if(!Array.isArray(eventTypes)||eventTypes.some(type=>typeof type!=='string'||!type)){
+        throw new TypeError('DOM event types must be non-empty strings.');
+    }
+    eventTypes=Object.freeze([...new Set(eventTypes)]);
+    if(!Number.isSafeInteger(maxValueLength)||maxValueLength<0
+        ||!Number.isSafeInteger(maxSerializedNodeLength)||maxSerializedNodeLength<0){
+        throw new RangeError('DOM capture length limits must be non-negative safe integers.');
+    }
+
+    for(const [name,value] of Object.entries({
+        captureEventDetails,captureInputValues,captureNodeMarkup,captureMutations,observeOpenShadowRoots
+    })){
+        if(typeof value!=='boolean')throw new TypeError(`${name} must be boolean.`);
+    }
+
+    const options={
+        captureEventDetails,captureInputValues,captureNodeMarkup,
+        maxValueLength,maxSerializedNodeLength
+    };
+    const observedRoots=new Set();
+    const listenerRegistrations=new Map();
+    let observer=null;
+    let active=false;
+    let cleanupPending=false;
+    let lifecycleStarted=false;
+    let pendingCausationId=null;
+    let causationTimer=null;
+
+    const removeInteractionListener=(target,type,handler)=>{
+        let failure=null;
+        for(let attempt=0;attempt<2;attempt+=1){
+            try{
+                target.removeEventListener(type,handler,true);
+                return null;
+            }catch(error){
+                failure=error;
+            }
+        }
+        return failure;
+    };
+
+    const disconnectObserver=()=>{
+        let failure=null;
+        for(let attempt=0;attempt<2;attempt+=1){
+            try{
+                observer?.disconnect();
+                return null;
+            }catch(error){
+                failure=error;
+            }
+        }
+        return failure;
+    };
+
+    const cleanupResources=()=>{
+        let failure=null;
+        for(const target of observedRoots){
+            const registrations=listenerRegistrations.get(target)??new Map();
+            for(const [type,handler] of [...registrations]){
+                const removalFailure=removeInteractionListener(target,type,handler);
+                if(removalFailure)failure??=removalFailure;
+                else registrations.delete(type);
+            }
+            if(registrations.size===0)listenerRegistrations.delete(target);
+        }
+        const observerFailure=disconnectObserver();
+        failure??=observerFailure;
+        if(failure){
+            active=true;
+            cleanupPending=true;
+            return failure;
+        }
+        observer=null;
+        listenerRegistrations.clear();
+        observedRoots.clear();
+        active=false;
+        cleanupPending=false;
+        pendingCausationId=null;
+        if(causationTimer!==null){
+            clearTimeout(causationTimer);
+            causationTimer=null;
+        }
+        return null;
+    };
+
+    const publish=(type,payload,metadata)=>{
+        const before=Number(eventManager.eventCount??0);
+        if(typeof eventManager.instrument==='function'){
+            eventManager.instrument(type,payload,{source:'dom',...metadata});
+        }else{
+            eventManager.emit(type,payload);
+        }
+        const recorded=Number(eventManager.eventCount??0)>before
+            ?eventManager.history?.[before]??null
+            :null;
+        return recorded?.type===type?recorded:null;
+    };
+
+    const interaction=(event,observedRoot)=>{
+        let path=[];
+        try{
+            if(typeof event?.composedPath==='function')path=event.composedPath();
+        }catch{}
+        const outermostObservedRoot=path.reduce(
+            (selected,item)=>observedRoots.has(item)?item:selected,
+            null
+        );
+        if(outermostObservedRoot&&outermostObservedRoot!==observedRoot){
+            return;
+        }
+        const record=publish(
+            DOM_INTERACTION_EVENT,
+            interactionRecord(event,root,options),
+            {category:'interaction'}
+        );
+        if(record?.id){
+            pendingCausationId=record.id;
+            if(causationTimer!==null)clearTimeout(causationTimer);
+            causationTimer=setTimeout(()=>{
+                if(pendingCausationId===record.id)pendingCausationId=null;
+                causationTimer=null;
+            },0);
+        }
+    };
+
+    const observeRoot=target=>{
+        if(!target||observedRoots.has(target))return;
+        const registrations=new Map();
+        observedRoots.add(target);
+        listenerRegistrations.set(target,registrations);
+        try{
+            for(const type of eventTypes){
+                const handler=event=>interaction(event,target);
+                target.addEventListener(type,handler,true);
+                registrations.set(type,handler);
+            }
+            observer?.observe(target,{
+                attributes:true,
+                attributeOldValue:true,
+                characterData:true,
+                characterDataOldValue:true,
+                childList:true,
+                subtree:true
+            });
+        }catch(error){
+            for(const [type,handler] of [...registrations]){
+                const removalFailure=removeInteractionListener(target,type,handler);
+                if(!removalFailure)registrations.delete(type);
+            }
+            if(registrations.size===0){
+                listenerRegistrations.delete(target);
+                observedRoots.delete(target);
+            }else{
+                active=true;
+                cleanupPending=true;
+            }
+            throw error;
+        }
+    };
+
+    const mutations=records=>{
+        for(const record of records){
+            publish(DOM_MUTATION_EVENT,mutationRecord(record,root,options),{
+                category:'mutation',
+                ...(pendingCausationId?{causationId:pendingCausationId}: {})
+            });
+            if(observeOpenShadowRoots&&record?.type==='childList'){
+                for(const node of record.addedNodes??[]){
+                    if(node?.shadowRoot)observeRoot(node.shadowRoot);
+                    for(const shadowRoot of collectOpenShadowRoots(node))observeRoot(shadowRoot);
+                }
+            }
+        }
+    };
+
+    function start(){
+        if(cleanupPending){
+            throw new Error('DOM instrumentation cleanup is pending; retry stop() before start().');
+        }
+        if(active)return api;
+        try{
+            if(captureMutations){
+                if(typeof MutationObserverImpl!=='function'){
+                    throw new TypeError('MutationObserver is required when DOM mutation capture is enabled.');
+                }
+                observer=new MutationObserverImpl(mutations);
+            }
+            observeRoot(root);
+            if(observeOpenShadowRoots){
+                for(const shadowRoot of collectOpenShadowRoots(root))observeRoot(shadowRoot);
+            }
+            active=true;
+            cleanupPending=false;
+            publish(DOM_OBSERVATION_STARTED_EVENT,{
+                root:rootDescription(root,options),
+                eventTypes:[...eventTypes],
+                captureEventDetails,
+                captureInputValues,
+                captureNodeMarkup,
+                captureMutations,
+                observeOpenShadowRoots
+            },{category:'lifecycle'});
+            lifecycleStarted=true;
+            return api;
+        }catch(error){
+            const cleanupFailure=cleanupResources();
+            if(!cleanupFailure)lifecycleStarted=false;
+            throw error;
+        }
+    }
+
+    function stop({emitLifecycle=true}={}){
+        if(typeof emitLifecycle!=='boolean')throw new TypeError('emitLifecycle must be boolean.');
+        if(!active)return api;
+        const shouldEmitLifecycle=emitLifecycle&&lifecycleStarted;
+        if(!emitLifecycle)lifecycleStarted=false;
+        const failure=cleanupResources();
+        if(failure)throw failure;
+        lifecycleStarted=false;
+        if(shouldEmitLifecycle){
+            publish(
+                DOM_OBSERVATION_STOPPED_EVENT,
+                {root:rootDescription(root,options)},
+                {category:'lifecycle'}
+            );
+        }
+        return api;
+    }
+
+    const api=Object.freeze({
+        root,
+        start,
+        stop,
+        get active(){return active;},
+        get cleanupPending(){return cleanupPending;},
+        get observedRootCount(){return observedRoots.size;}
+    });
+    return api;
+}