@wenathlan/extension 1.1.33 → 1.1.34

package/README.md

@@ -2,17 +2,19 @@
 
 Devthink is a **consent-first browser-agent bridge** distributed as a TypeScript library and a Chromium Manifest V3 extension. It turns a user-provided browser objective into a bounded, reviewable plan. The user must start the active-tab session and approve the plan before any page action reaches the browser.
 
-Version: **1.1.33**. License: **GPL-3.0-only**. The repository is `wenathlan/extension`; the npm-compatible scoped package identifier is `@wenathlan/extension`.
+Version: **1.1.34**. License: **GPL-3.0-only**. The repository is `wenathlan/extension`; the npm-compatible scoped package identifier is `@wenathlan/extension`.
 
 ## What it does
 
-| Capability | Behavior in 1.1.33 |
+| Capability | Behavior in 1.1.34 |
 | --- | --- |
 | Active-tab session | The user starts a short-lived session for one HTTPS tab and one origin; the session records its origin grants. |
 | Page observation | The extension captures the complete semantic inventory: every interactive element, every form control, every select option and the full page text. |
 | Plan proposal | A local plan can be created immediately; an optional user-configured HTTPS endpoint can return a typed plan proposal of any length. |
 | Review gate | Every remote proposal starts in `pending`; it cannot reach the page bridge before explicit approval. |
-| Browser tools | Reviewed plans cover ninety action kinds: pointer paths and coordinate clicks, text, aria, name, xpath, index and point target resolution, timed typing, key holds, sliders, dates, colors, shadow dom piercing, iframe entry, dialog answering, retry rules, a complete read vocabulary with clickable maps and verification reads, page mutation under review, and browser-level tab, window, zoom, snapshot and download commands. |
+| Browser tools | Reviewed plans cover one hundred eighteen action kinds: pointer paths and coordinate clicks, text, aria, name, xpath, index and point target resolution, timed typing, key holds, sliders, dates, colors, shadow dom piercing, iframe entry, dialog answering, retry rules, a complete read vocabulary with clickable maps and verification reads, page mutation under review, and browser-level tab, window, zoom, snapshot and download commands. |
+| Observation depth | The agent sees the whole page read only: the accessibility tree beside the dom snapshot, reader views, visible text, outlines, selections, open graph and embedded json state, plus detected lists, tables, pagination, infinite scroll, virtualization, lazy images, sticky overlays and scroll locks offered as plan suggestions. |
+| Watch vocabulary | `watchmutate`, `watchfocus` and `watchbanner` observe the page across a reviewed lifetime window with batched event records, `waitquiet` waits for network quiet under a reviewed threshold, `diffsnapshots` diffs two stored observation versions into added, removed and changed rows, and `deriveselector` ranks stable selector candidates with stability scores; registrations persist across service worker restarts. |
 | Target resolution | Steps address elements through reviewed `targetref` modes: css selector, visible text, aria role and name, accessible name, xpath, clickable map index or viewport point; ambiguous matches are refused with candidate lists and every resolution returns a matched element summary for review. |
 | Optional capabilities | `tabs`, `downloads`, `clipboardRead` and `clipboardWrite` are optional permissions; browser kinds check their capability, the review panel can request a grant and every grant is audited. |
 | Unlimited by choice | Wait durations, plan size, plan expiry, audit retention and outcome retention carry no code ceilings; every bound is a user choice. |
@@ -46,10 +48,10 @@ The endpoint field intentionally has no default URL. Enter a URL such as `https:
 
 ```json
 {
-  "version": "1.1.33",
+  "version": "1.1.34",
   "objective": "User supplied objective",
   "session": { "id": "uuid", "tabid": 1, "origin": "https://example.com" },
-  "observation": { "schemaversion": 2, "url": "https://example.com/path", "interactive": [] },
+  "observation": { "schemaversion": 3, "url": "https://example.com/path", "interactive": [] },
   "capabilities": { "tabs": false, "downloads": false, "clipboardread": false, "clipboardwrite": false }
 }
 ```

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export * from "./memory.js";
-export { actionrisk as deriveactionrisk, canexecute, hostpattern, normalizeendpoint, resolutionverdict, validatestep, validatetargetref } from "./policy.js";
+export { actionrisk as deriveactionrisk, canexecute, hostpattern, iswatchkind, normalizeendpoint, observationmodeof, resolutionverdict, validatestep, validatetargetref } from "./policy.js";
 export * from "./protocol.js";
 export * from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,UAAU,IAAI,gBAAgB,EAAE,UAAU,EAAE,WAAW,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC7J,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,UAAU,IAAI,gBAAgB,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC7L,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -128,6 +128,116 @@ var sessionmemory = class {
   async setdialogpolicy(policy) {
     return this.adapter.set("dialogpolicy", policy);
   }
+  /** Stores one observation capture under its version so every observation version stays available. */
+  async setobservation(record2) {
+    return this.adapter.set(`observation${record2.version}`, record2);
+  }
+  /** Returns one stored observation version. */
+  async getobservation(version) {
+    return this.adapter.get(`observation${version}`);
+  }
+  /** Returns the observation retention window; an absent setting keeps every capture. */
+  async observationretention() {
+    return (await this.getsettings())?.observationretention;
+  }
+  /** Stores one accessibility tree capture; retention is a user setting and an absent setting keeps every tree. */
+  async adda11ytree(capture) {
+    const records = await this.geta11ytrees();
+    const combined = [capture, ...records];
+    const retention = await this.observationretention();
+    await this.adapter.set("a11ytrees", retention === void 0 ? combined : combined.slice(0, retention));
+  }
+  /** Returns every stored accessibility tree capture, newest first. */
+  async geta11ytrees() {
+    return await this.adapter.get("a11ytrees") ?? [];
+  }
+  /** Stores one reader article capture; retention is a user setting and an absent setting keeps every article. */
+  async addreaderarticle(capture) {
+    const records = await this.getreaderarticles();
+    const combined = [capture, ...records];
+    const retention = await this.observationretention();
+    await this.adapter.set("readerarticles", retention === void 0 ? combined : combined.slice(0, retention));
+  }
+  /** Returns every stored reader article capture, newest first. */
+  async getreaderarticles() {
+    return await this.adapter.get("readerarticles") ?? [];
+  }
+  /** Records one dom mutation observed inside a reviewed watch. */
+  async addmutationevent(event) {
+    const records = await this.getmutationevents();
+    await this.adapter.set("mutationevents", [event, ...records]);
+  }
+  /** Returns the mutation event stream of every reviewed watch. */
+  async getmutationevents() {
+    return await this.adapter.get("mutationevents") ?? [];
+  }
+  /** Records one focus change observed inside a reviewed watch. */
+  async addfocusevent(event) {
+    const records = await this.getfocusevents();
+    await this.adapter.set("focusevents", [event, ...records]);
+  }
+  /** Returns the focus event stream of every reviewed watch. */
+  async getfocusevents() {
+    return await this.adapter.get("focusevents") ?? [];
+  }
+  /** Records one consent banner observed by a reviewed banner watch. */
+  async addbanner(event) {
+    const records = await this.getbanners();
+    await this.adapter.set("banners", [event, ...records]);
+  }
+  /** Returns every consent banner report observed so far. */
+  async getbanners() {
+    return await this.adapter.get("banners") ?? [];
+  }
+  /** Records one snapshot diff between two observation versions. */
+  async adddiff(diff) {
+    const records = await this.getdiffs();
+    await this.adapter.set("diffs", [diff, ...records]);
+  }
+  /** Returns every stored snapshot diff, newest first. */
+  async getdiffs() {
+    return await this.adapter.get("diffs") ?? [];
+  }
+  /** Records one derived selector with its stability score for reuse. */
+  async addselector(selector) {
+    const records = await this.getselectors();
+    await this.adapter.set("selectors", [selector, ...records]);
+  }
+  /** Returns every stored derived selector with its stability score, newest first. */
+  async getselectors() {
+    return await this.adapter.get("selectors") ?? [];
+  }
+  /** Records one detected template class or section fingerprint for its origin. */
+  async addtemplate(profile) {
+    const records = await this.gettemplates();
+    await this.adapter.set("templates", [profile, ...records]);
+  }
+  /** Returns every stored template class and section fingerprint, newest first. */
+  async gettemplates() {
+    return await this.adapter.get("templates") ?? [];
+  }
+  /** Records one watch registration so it survives service worker restarts. */
+  async addwatch(watch) {
+    const records = await this.getwatches();
+    await this.adapter.set("watches", [watch, ...records]);
+  }
+  /** Returns every watch registration, newest first, including closed windows. */
+  async getwatches() {
+    return await this.adapter.get("watches") ?? [];
+  }
+  /** Closes one watch registration by watch id once its reviewed lifetime window ends. */
+  async closewatch(watchid, closedat) {
+    const records = await this.getwatches();
+    await this.adapter.set("watches", records.map((watch) => watch.watchid === watchid && watch.closedat === void 0 ? { ...watch, closedat } : watch));
+  }
+  /** Returns the live page signals of language, template, scroll lock and banner state. */
+  async getsignals() {
+    return this.adapter.get("signals");
+  }
+  /** Replaces the live page signals after an observation step refreshes them. */
+  async setsignals(signals) {
+    return this.adapter.set("signals", signals);
+  }
 };
 function randomid() {
   return crypto.randomUUID();
@@ -136,9 +246,10 @@ function randomid() {
 // policy.ts
 var sensitiveactions = /* @__PURE__ */ new Set(["click", "type", "navigate", "select", "presskey", "drag", "drop", "upload", "clear", "check", "uncheck", "toggle", "submit", "reload", "back", "forward", "writestorage", "setattribute", "removeattribute", "evaluate", "tabcreate", "tabactivate", "tabclose", "tabreload", "windowcreate", "windowclose", "windowresize", "downloadfile", "clickpoint", "shiftclick", "dismissdialog", "enterframe", "typetime", "appendtext", "setvalue", "typeedit", "keyhold", "keyrelease", "submitsearch", "selectmulti", "chooseradio", "setslider", "setdate", "setcolor"]);
 var interactionactions = /* @__PURE__ */ new Set(["focus", "scroll", "hover", "clickdeep", "rightclick", "doubleclick", "scrollpage", "scrollby", "scrollend", "scrolltop", "fullscreen", "zoomset", "movepointer", "clicktext", "clickaria", "clickname", "expanddetails", "pierceshadow", "retryaction"]);
-var readactions = /* @__PURE__ */ new Set(["observe", "inspect", "extract", "wait", "waitfor", "waittext", "readattribute", "readstyle", "readgeometry", "readvalue", "readtext", "readhtml", "countelements", "readtable", "readlinks", "readimages", "readmeta", "readforms", "readstorage", "highlight", "tablist", "windowlist", "tabsnapshot", "mapclicks", "verifyvisible", "verifyenabled", "resolvexpath"]);
+var readactions = /* @__PURE__ */ new Set(["observe", "inspect", "extract", "wait", "waitfor", "waittext", "readattribute", "readstyle", "readgeometry", "readvalue", "readtext", "readhtml", "countelements", "readtable", "readlinks", "readimages", "readmeta", "readforms", "readstorage", "highlight", "tablist", "windowlist", "tabsnapshot", "mapclicks", "verifyvisible", "verifyenabled", "resolvexpath", "a11ytree", "readvisible", "readertree", "detectlists", "detecttables", "readjson", "watchmutate", "waitquiet", "watchbanner", "detectinfinitescroll", "detectvirtual", "detectlazy", "readscrollpos", "readlang", "readoutline", "countpages", "listshadow", "listframes", "classifypage", "fingerprintsection", "diffsnapshots", "readselection", "watchfocus", "detectsticky", "detectscrolllock", "readopengraph", "detectlanguage", "deriveselector"]);
 var allowedactions = /* @__PURE__ */ new Set([...sensitiveactions, ...interactionactions, ...readactions]);
-var targetactions = /* @__PURE__ */ new Set(["inspect", "focus", "click", "type", "scroll", "select", "hover", "clickdeep", "rightclick", "doubleclick", "drag", "drop", "upload", "clear", "check", "uncheck", "toggle", "submit", "readattribute", "readstyle", "readgeometry", "readvalue", "readtext", "readhtml", "countelements", "readtable", "highlight", "setattribute", "removeattribute", "waitfor", "shiftclick", "typetime", "appendtext", "setvalue", "typeedit", "submitsearch", "selectmulti", "chooseradio", "setslider", "setdate", "setcolor", "expanddetails", "verifyvisible", "verifyenabled", "pierceshadow"]);
+var watchactions = /* @__PURE__ */ new Set(["watchmutate", "watchbanner", "watchfocus"]);
+var targetactions = /* @__PURE__ */ new Set(["inspect", "focus", "click", "type", "scroll", "select", "hover", "clickdeep", "rightclick", "doubleclick", "drag", "drop", "upload", "clear", "check", "uncheck", "toggle", "submit", "readattribute", "readstyle", "readgeometry", "readvalue", "readtext", "readhtml", "countelements", "readtable", "highlight", "setattribute", "removeattribute", "waitfor", "shiftclick", "typetime", "appendtext", "setvalue", "typeedit", "submitsearch", "selectmulti", "chooseradio", "setslider", "setdate", "setcolor", "expanddetails", "verifyvisible", "verifyenabled", "pierceshadow", "deriveselector", "fingerprintsection"]);
 var valueactions = /* @__PURE__ */ new Set(["presskey", "drag", "drop", "upload", "readattribute", "removeattribute", "waittext", "evaluate", "zoomset", "tabactivate", "tabclose", "tabreload", "windowclose", "windowresize", "tabcreate", "windowcreate", "downloadfile", "typetime", "appendtext", "setvalue", "typeedit", "keyhold", "keyrelease", "chooseradio", "setslider", "setdate", "setcolor"]);
 function normalizeendpoint(value) {
   const endpoint = new URL(value.trim());
@@ -151,6 +262,14 @@ function hostpattern(origin) {
   if (parsed.protocol !== "https:") throw new Error("Only HTTPS origins can be granted.");
   return `${parsed.origin}/*`;
 }
+function iswatchkind(kind) {
+  return watchactions.has(kind);
+}
+function observationmodeof(kind) {
+  if (watchactions.has(kind) || kind === "waitquiet") return "watching";
+  if (kind === "diffsnapshots") return "diffing";
+  return "passive";
+}
 function actionrisk(kind) {
   if (!allowedactions.has(kind)) throw new Error("Unsupported browser action.");
   if (sensitiveactions.has(kind)) return "sensitive";
@@ -361,6 +480,24 @@ function validatestep(step, origin) {
     if (!nonnegativeoption(retry, "settle")) return { allowed: false, reason: "The reviewed retry settle window must be zero or a positive number of milliseconds." };
     if (!nonnegativeoption(retry, "tolerance")) return { allowed: false, reason: "The reviewed retry movement tolerance must be zero or a positive number of pixels." };
   }
+  if (watchactions.has(step.kind)) {
+    if (typeof options.lifetime !== "number" || !Number.isFinite(options.lifetime) || options.lifetime <= 0) return { allowed: false, reason: "A reviewed watch lifetime window in milliseconds is required in options." };
+    if (options.scopes !== void 0 && (!Array.isArray(options.scopes) || !options.scopes.every((scope) => isnonempty(scope)))) return { allowed: false, reason: "The reviewed watch scopes must be a list of non-empty selectors." };
+    if (options.events !== void 0 && (!Array.isArray(options.events) || !options.events.every((event) => isnonempty(event)))) return { allowed: false, reason: "The reviewed watch event kinds must be a list of non-empty strings." };
+    if (!nonnegativeoption(options, "poll")) return { allowed: false, reason: "The reviewed watch poll interval must be zero or a positive number of milliseconds." };
+  }
+  if (step.kind === "waitquiet") {
+    const rule = options.quietrule;
+    if (!rule || typeof rule !== "object" || Array.isArray(rule)) return { allowed: false, reason: "A reviewed quietrule with an idle threshold is required in options." };
+    const quiet = rule;
+    if (typeof quiet.idle !== "number" || !Number.isFinite(quiet.idle) || quiet.idle <= 0) return { allowed: false, reason: "The reviewed quiet idle threshold must be a positive number of milliseconds with no code ceiling." };
+    if (!nonnegativeoption(quiet, "poll")) return { allowed: false, reason: "The reviewed quiet poll interval must be zero or a positive number of milliseconds." };
+    if (!nonnegativeoption(quiet, "timeout")) return { allowed: false, reason: "The reviewed quiet timeout must be zero or a positive number of milliseconds." };
+  }
+  if (step.kind === "diffsnapshots") {
+    const versions = options.versions;
+    if (!Array.isArray(versions) || versions.length !== 2 || !versions.every((version) => typeof version === "number" && Number.isInteger(version) && version >= 1)) return { allowed: false, reason: "Two reviewed observation version numbers are required in options." };
+  }
   return { allowed: true };
 }
 function sessiongate(input) {
@@ -377,11 +514,12 @@ function canexecute(input) {
   if (!input.plan || input.plan.state !== "approved") return { allowed: false, reason: "The plan has not received explicit approval." };
   if (input.plan.expiresat <= now) return { allowed: false, reason: "The approved plan has expired." };
   if ((input.step.kind === "pierceshadow" || input.step.kind === "enterframe") && !origingranted(input.session, input.origin)) return { allowed: false, reason: "The shadow or frame step is outside the session origin grants." };
+  if (input.step.kind === "readjson" && !origingranted(input.session, input.origin)) return { allowed: false, reason: "The json state read is outside the session origin grants." };
   return validatestep(input.step, input.origin);
 }
 
 // version.ts
-var packageversion = "1.1.33";
+var packageversion = "1.1.34";
 
 // types.ts
 var protocolversion = packageversion;
@@ -448,20 +586,49 @@ function mapresponse(input) {
 function heldkeysreport(input) {
   return { version: protocolversion, tabid: input.tabid, heldkeys: input.holds };
 }
+function observationresponse(input) {
+  return JSON.stringify({ version: protocolversion, planid: input.plan.id, planstate: input.plan.state, observation: input.observation });
+}
+function eventresponse(input) {
+  return JSON.stringify({ version: protocolversion, planid: input.plan.id, planstate: input.plan.state, events: input.events });
+}
+function diffresponse(input) {
+  return JSON.stringify({ version: protocolversion, planid: input.plan.id, planstate: input.plan.state, diff: input.diff });
+}
+function signalsreport(input) {
+  const signals = input.signals;
+  return {
+    version: protocolversion,
+    ...signals && signals.language !== void 0 ? { language: signals.language } : {},
+    ...signals && signals.template !== void 0 ? { template: signals.template } : {},
+    ...signals && signals.scrolllocked !== void 0 ? { scrolllocked: signals.scrolllocked } : {},
+    ...signals && signals.banner !== void 0 ? { banner: signals.banner } : {}
+  };
+}
+function selectorresponse(input) {
+  return JSON.stringify({ version: protocolversion, planid: input.plan.id, planstate: input.plan.state, candidates: input.candidates });
+}
 export {
   canexecute,
   actionrisk as deriveactionrisk,
+  diffresponse,
+  eventresponse,
   heldkeysreport,
   hostpattern,
+  iswatchkind,
   mapresponse,
   normalizeendpoint,
+  observationmodeof,
+  observationresponse,
   outcomeresponse,
   parseproposal,
   protocolversion,
   randomid,
   requestbody,
   resolutionverdict,
+  selectorresponse,
   sessionmemory,
+  signalsreport,
   validatestep,
   validatetargetref
 };