@openpicker/protocol 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Usertour
+
+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,36 @@
+# @openpicker/protocol
+
+The open [openpicker](https://openpicker.dev) postMessage protocol: the wire types, constants, and
+selector helpers that the browser extension and any client share. Website:
+[openpicker.dev](https://openpicker.dev) · Docs: [docs.openpicker.dev](https://docs.openpicker.dev)
+
+Most integrations should use [`@openpicker/sdk`](https://www.npmjs.com/package/@openpicker/sdk),
+which wraps this protocol in a friendly client. Depend on this package directly only when building
+your own client (another SDK, a different extension, a non-browser bridge) against the same wire
+format.
+
+```bash
+npm install @openpicker/protocol
+```
+
+```ts
+import {
+  CHANNEL,
+  PROTOCOL_VERSION,
+  isEnvelope,
+  matchesSelectorConfig,
+  type PickParams,
+  type SelectorConfig,
+} from "@openpicker/protocol"
+```
+
+This package ships:
+
+- **Constants** — `CHANNEL`, `PROTOCOL_VERSION`.
+- **Envelopes** — `RequestEnvelope`, `ResponseEnvelope`, `EventEnvelope`, and the `isEnvelope` guard.
+- **Methods** — `MethodMap` plus the params/result types (`PickParams`, `PickResult`, `SelectorConfig`, …).
+- **Errors** — `ProtocolError`, `ErrorCode`.
+- **Selector helpers** — `tokenizeSelector`, `matchesSelectorConfig`, and their token types.
+
+See the [protocol spec](https://github.com/usertour/openpicker/blob/main/PROTOCOL.md) for the full
+wire format.

package/dist/index.cjs

@@ -0,0 +1,153 @@
+'use strict';
+
+// src/constants.ts
+var CHANNEL = "openpicker";
+var PROTOCOL_VERSION = 1;
+
+// src/envelope.ts
+function isEnvelope(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  return v.channel === CHANNEL && typeof v.kind === "string";
+}
+
+// src/selectorTokens.ts
+var WORD = /[\w-]/;
+function tokenizeSelector(selector) {
+  const tokens = [];
+  const n = selector.length;
+  let i = 0;
+  const push = (text, type) => {
+    if (text) tokens.push({ text, type });
+  };
+  const runOfWord = (from) => {
+    let j = from;
+    while (j < n && WORD.test(selector.charAt(j))) j++;
+    return j;
+  };
+  while (i < n) {
+    const c = selector.charAt(i);
+    if (/\s/.test(c)) {
+      let j = i + 1;
+      while (j < n && /\s/.test(selector.charAt(j))) j++;
+      push(selector.slice(i, j), "combinator");
+      i = j;
+      continue;
+    }
+    if (c === ">" || c === "+" || c === "~") {
+      push(c, "combinator");
+      i++;
+      continue;
+    }
+    if (c === "#") {
+      const j = runOfWord(i + 1);
+      push(selector.slice(i, j), "id");
+      i = j;
+      continue;
+    }
+    if (c === ".") {
+      const j = runOfWord(i + 1);
+      push(selector.slice(i, j), "class");
+      i = j;
+      continue;
+    }
+    if (c === ":") {
+      let j = i + 1;
+      if (selector.charAt(j) === ":") j++;
+      j = runOfWord(j);
+      if (selector.charAt(j) === "(") {
+        let depth = 0;
+        while (j < n) {
+          const ch = selector.charAt(j);
+          j++;
+          if (ch === "(") depth++;
+          else if (ch === ")") {
+            depth--;
+            if (depth === 0) break;
+          }
+        }
+      }
+      push(selector.slice(i, j), "pseudo");
+      i = j;
+      continue;
+    }
+    if (c === "[") {
+      push("[", "punctuation");
+      i++;
+      i = (() => {
+        const nameEnd = runOfWord(i);
+        push(selector.slice(i, nameEnd), "attrName");
+        let k = nameEnd;
+        while (k < n && selector.charAt(k) !== "]") {
+          const ch = selector.charAt(k);
+          if (ch === '"' || ch === "'") {
+            let q = k + 1;
+            while (q < n && selector.charAt(q) !== ch) q++;
+            if (q < n) q++;
+            push(selector.slice(k, q), "attrValue");
+            k = q;
+          } else if (/[\s~|^$*=]/.test(ch)) {
+            push(ch, "punctuation");
+            k++;
+          } else {
+            let v = k;
+            while (v < n && !/[\]\s=~|^$*'"]/.test(selector.charAt(v))) v++;
+            push(selector.slice(k, v), "attrValue");
+            k = v;
+          }
+        }
+        return k;
+      })();
+      if (i < n && selector.charAt(i) === "]") {
+        push("]", "punctuation");
+        i++;
+      }
+      continue;
+    }
+    if (c === "*") {
+      push("*", "tag");
+      i++;
+      continue;
+    }
+    if (WORD.test(c)) {
+      const j = runOfWord(i);
+      push(selector.slice(i, j), "tag");
+      i = j;
+      continue;
+    }
+    push(c, "punctuation");
+    i++;
+  }
+  return tokens;
+}
+function anchorAllowsName(name, anchor) {
+  if (!anchor) return true;
+  if (anchor.enabled === false) return false;
+  try {
+    if (anchor.ignore && new RegExp(anchor.ignore).test(name)) return false;
+    if (anchor.allow) return new RegExp(anchor.allow).test(name);
+  } catch {
+    return true;
+  }
+  return true;
+}
+function matchesSelectorConfig(selector, config) {
+  for (const tok of tokenizeSelector(selector)) {
+    if (tok.type === "id") {
+      if (!anchorAllowsName(tok.text.replace(/^#/, ""), config.id)) return false;
+    } else if (tok.type === "class") {
+      if (!anchorAllowsName(tok.text.replace(/^\./, ""), config.class)) return false;
+    } else if (tok.type === "tag") {
+      if (tok.text !== "*" && !anchorAllowsName(tok.text, config.tag)) return false;
+    } else if (tok.type === "attrName") {
+      if (!anchorAllowsName(tok.text, config.attr)) return false;
+    }
+  }
+  return true;
+}
+
+exports.CHANNEL = CHANNEL;
+exports.PROTOCOL_VERSION = PROTOCOL_VERSION;
+exports.isEnvelope = isEnvelope;
+exports.matchesSelectorConfig = matchesSelectorConfig;
+exports.tokenizeSelector = tokenizeSelector;

package/dist/index.d.cts

@@ -0,0 +1,228 @@
+/**
+ * Fixed discriminator carried on every openpicker message. Receivers ignore any
+ * message whose `channel` is not exactly this value.
+ */
+declare const CHANNEL: "openpicker";
+type Channel = typeof CHANNEL;
+/** Protocol major version implemented by this package. See PROTOCOL.md §9. */
+declare const PROTOCOL_VERSION: 1;
+/** The three message kinds that share the envelope. */
+type MessageKind = "req" | "res" | "evt";
+
+/** Stable error identifiers returned on a failed response. See PROTOCOL.md §8. */
+type ErrorCode = "extension_not_installed" | "unsupported_protocol" | "consent_denied" | "cancelled" | "invalid_params" | "unsupported" | "timeout" | "internal_error";
+/** Error payload carried on a failed response envelope (`ok: false`). */
+interface ProtocolError {
+    code: ErrorCode;
+    message: string;
+    data?: unknown;
+}
+
+/**
+ * What the returned screenshot covers. See DESIGN.md §5b.
+ * - "none": no screenshot.
+ * - "element": cropped to the selected element.
+ * - "viewport": the full visible viewport.
+ * ("fullpage" is reserved for the future.)
+ */
+type ScreenshotMode = "none" | "element" | "viewport";
+/** A regular-expression source string. Compiled with `new RegExp(...)` — never eval'd. */
+type RegexSource = string;
+/**
+ * Rules for one anchor type (id / class / attr / tag) when building a selector.
+ * This mirrors the in-picker gear settings; passed via {@link PickParams.selector}
+ * it pre-fills them. For `attr`, `allow`/`ignore` match the attribute NAME.
+ */
+interface SelectorAnchorConfig {
+    /** Whether this anchor type may be used at all. Default: true. */
+    enabled?: boolean;
+    /**
+     * Only names matching this regex may be used. Omitted/empty = openpicker's
+     * built-in "stable name" heuristics (skips ember/radix ids, hashed CSS-in-JS /
+     * CSS-module classes, etc.).
+     */
+    allow?: RegexSource;
+    /** Names matching this regex are never used (applied on top of `allow`). */
+    ignore?: RegexSource;
+}
+/** Per-dimension selector-generation rules. See {@link SelectorAnchorConfig}. */
+interface SelectorConfig {
+    id?: SelectorAnchorConfig;
+    class?: SelectorAnchorConfig;
+    attr?: SelectorAnchorConfig;
+    tag?: SelectorAnchorConfig;
+}
+interface PingParams {
+    /** Display-only application name, surfaced in the consent prompt. Never trusted. */
+    appName?: string;
+}
+interface PingResult {
+    /** The extension's own version (from its manifest). */
+    extensionVersion: string;
+    /** Protocol majors the extension supports. */
+    protocolVersions: number[];
+    /** Feature flags so the SDK can degrade gracefully. */
+    capabilities: string[];
+}
+interface PickParams {
+    /** Request resolution of elements inside iframes (may be reported unsupported in v1). */
+    iframe?: boolean;
+    /**
+     * Screenshot to include in the result. A {@link ScreenshotMode}, or a boolean for
+     * compatibility (`true` → "element", `false` → "none"). Defaults to "none".
+     */
+    screenshot?: ScreenshotMode | boolean;
+    /**
+     * The URL to pick in. The extension opens it in a tab, the user picks there, and
+     * the result is routed back to the calling tab (cross-tab picking). Required: an
+     * extension earns its keep by crossing the tab/origin boundary — a page can
+     * already script its own DOM, so same-tab picking is not an SDK capability (only
+     * the toolbar offers it, for humans). Requires the "openUrl" capability.
+     */
+    url: string;
+    /**
+     * Optional opaque identifier for "which task" this pick is for. Only used to
+     * decide whether a follow-up cross-tab pick reuses the existing target tab or
+     * opens a new one (equality compare; never interpreted). See DESIGN.md §5d.
+     */
+    key?: string;
+    /** Display-only application name, surfaced in the consent prompt. Never trusted. */
+    appName?: string;
+    /**
+     * Initial selector-generation rules for this pick (also the values shown in the
+     * gear). Composed (AND) with the user's saved rules — both can only narrow.
+     * Omitted dimensions use openpicker's defaults.
+     */
+    selector?: SelectorConfig;
+    /** Open the gear settings read-only (the user can see them but not change). Default: false. */
+    lockSelectorSettings?: boolean;
+    /** Make the selector field read-only (no hand-editing). Default: false. */
+    lockSelectorEdit?: boolean;
+    /** Only allow confirming (OK) when the selector matches exactly one element. Default: false. */
+    requireUniqueMatch?: boolean;
+}
+interface PickedElement {
+    tag: string;
+    id?: string;
+    classes?: string[];
+    text?: string;
+    attributes?: Record<string, string>;
+}
+interface PickResult {
+    /** The chosen CSS selector. */
+    selector: string;
+    /** How many elements the selector currently matches. */
+    matchCount: number;
+    /** A summary of the selected element. */
+    element: PickedElement;
+    /** Present only when `screenshot` was requested. */
+    screenshot?: string;
+}
+type CancelParams = Record<string, never>;
+type CancelResult = Record<string, never>;
+interface HighlightParams {
+    selector: string;
+}
+interface HighlightResult {
+    matchCount: number;
+}
+type ClearHighlightParams = Record<string, never>;
+type ClearHighlightResult = Record<string, never>;
+type ActivateSelfParams = Record<string, never>;
+type ActivateSelfResult = Record<string, never>;
+type IsTargetOpenParams = Record<string, never>;
+interface IsTargetOpenResult {
+    /** Whether a cross-tab target tab opened by this source is still open. */
+    open: boolean;
+}
+/** Maps each method name to its request params and response result. */
+interface MethodMap {
+    ping: {
+        params: PingParams;
+        result: PingResult;
+    };
+    pick: {
+        params: PickParams;
+        result: PickResult;
+    };
+    cancel: {
+        params: CancelParams;
+        result: CancelResult;
+    };
+    highlight: {
+        params: HighlightParams;
+        result: HighlightResult;
+    };
+    clearHighlight: {
+        params: ClearHighlightParams;
+        result: ClearHighlightResult;
+    };
+    /** Bring the calling tab to the foreground (it can only focus itself). */
+    activateSelf: {
+        params: ActivateSelfParams;
+        result: ActivateSelfResult;
+    };
+    /** Report whether the cross-tab target opened by this source is still open. */
+    isTargetOpen: {
+        params: IsTargetOpenParams;
+        result: IsTargetOpenResult;
+    };
+}
+type MethodName = keyof MethodMap;
+
+/** A method call: SDK → extension. See PROTOCOL.md §3. */
+interface RequestEnvelope<M extends MethodName = MethodName> {
+    channel: Channel;
+    v: number;
+    kind: "req";
+    id: string;
+    method: M;
+    params: MethodMap[M]["params"];
+}
+/** A reply to a request: extension → SDK. `id` echoes the request. */
+interface ResponseEnvelope<M extends MethodName = MethodName> {
+    channel: Channel;
+    v: number;
+    kind: "res";
+    id: string;
+    ok: boolean;
+    result?: MethodMap[M]["result"];
+    error?: ProtocolError;
+}
+/** Reserved notification names (none required in v1). See PROTOCOL.md §6.6. */
+type EventName = "hoverChange" | "consentChange";
+/** A fire-and-forget notification, not correlated to a single request. */
+interface EventEnvelope {
+    channel: Channel;
+    v: number;
+    kind: "evt";
+    event: EventName;
+    data: unknown;
+}
+type Envelope = RequestEnvelope | ResponseEnvelope | EventEnvelope;
+/** Narrowing guard: is this an openpicker envelope at all? */
+declare function isEnvelope(value: unknown): value is Envelope;
+
+/**
+ * Tokenize a CSS selector for syntax highlighting and for validating a selector
+ * against a {@link SelectorConfig}. Best-effort and resilient: anything
+ * unrecognized falls through as "punctuation", so an in-progress or invalid
+ * selector still tokenizes without throwing. Invariant: the concatenated token text
+ * always equals the input exactly. Lives in the protocol package so both the
+ * extension (highlighting) and the SDK (validation) can share it.
+ */
+type SelectorTokenType = "tag" | "id" | "class" | "attrName" | "attrValue" | "pseudo" | "combinator" | "punctuation";
+interface SelectorToken {
+    text: string;
+    type: SelectorTokenType;
+}
+declare function tokenizeSelector(selector: string): SelectorToken[];
+/**
+ * Whether a CSS selector only uses anchors permitted by a {@link SelectorConfig} —
+ * the SDK-side check a developer runs on the returned selector (which the user may
+ * have hand-edited). Combinators, pseudo-classes, attribute values, and the
+ * universal `*` are unconstrained. A selector touching no constrained anchors passes.
+ */
+declare function matchesSelectorConfig(selector: string, config: SelectorConfig): boolean;
+
+export { type ActivateSelfParams, type ActivateSelfResult, CHANNEL, type CancelParams, type CancelResult, type Channel, type ClearHighlightParams, type ClearHighlightResult, type Envelope, type ErrorCode, type EventEnvelope, type EventName, type HighlightParams, type HighlightResult, type IsTargetOpenParams, type IsTargetOpenResult, type MessageKind, type MethodMap, type MethodName, PROTOCOL_VERSION, type PickParams, type PickResult, type PickedElement, type PingParams, type PingResult, type ProtocolError, type RegexSource, type RequestEnvelope, type ResponseEnvelope, type ScreenshotMode, type SelectorAnchorConfig, type SelectorConfig, type SelectorToken, type SelectorTokenType, isEnvelope, matchesSelectorConfig, tokenizeSelector };

package/dist/index.d.ts

@@ -0,0 +1,228 @@
+/**
+ * Fixed discriminator carried on every openpicker message. Receivers ignore any
+ * message whose `channel` is not exactly this value.
+ */
+declare const CHANNEL: "openpicker";
+type Channel = typeof CHANNEL;
+/** Protocol major version implemented by this package. See PROTOCOL.md §9. */
+declare const PROTOCOL_VERSION: 1;
+/** The three message kinds that share the envelope. */
+type MessageKind = "req" | "res" | "evt";
+
+/** Stable error identifiers returned on a failed response. See PROTOCOL.md §8. */
+type ErrorCode = "extension_not_installed" | "unsupported_protocol" | "consent_denied" | "cancelled" | "invalid_params" | "unsupported" | "timeout" | "internal_error";
+/** Error payload carried on a failed response envelope (`ok: false`). */
+interface ProtocolError {
+    code: ErrorCode;
+    message: string;
+    data?: unknown;
+}
+
+/**
+ * What the returned screenshot covers. See DESIGN.md §5b.
+ * - "none": no screenshot.
+ * - "element": cropped to the selected element.
+ * - "viewport": the full visible viewport.
+ * ("fullpage" is reserved for the future.)
+ */
+type ScreenshotMode = "none" | "element" | "viewport";
+/** A regular-expression source string. Compiled with `new RegExp(...)` — never eval'd. */
+type RegexSource = string;
+/**
+ * Rules for one anchor type (id / class / attr / tag) when building a selector.
+ * This mirrors the in-picker gear settings; passed via {@link PickParams.selector}
+ * it pre-fills them. For `attr`, `allow`/`ignore` match the attribute NAME.
+ */
+interface SelectorAnchorConfig {
+    /** Whether this anchor type may be used at all. Default: true. */
+    enabled?: boolean;
+    /**
+     * Only names matching this regex may be used. Omitted/empty = openpicker's
+     * built-in "stable name" heuristics (skips ember/radix ids, hashed CSS-in-JS /
+     * CSS-module classes, etc.).
+     */
+    allow?: RegexSource;
+    /** Names matching this regex are never used (applied on top of `allow`). */
+    ignore?: RegexSource;
+}
+/** Per-dimension selector-generation rules. See {@link SelectorAnchorConfig}. */
+interface SelectorConfig {
+    id?: SelectorAnchorConfig;
+    class?: SelectorAnchorConfig;
+    attr?: SelectorAnchorConfig;
+    tag?: SelectorAnchorConfig;
+}
+interface PingParams {
+    /** Display-only application name, surfaced in the consent prompt. Never trusted. */
+    appName?: string;
+}
+interface PingResult {
+    /** The extension's own version (from its manifest). */
+    extensionVersion: string;
+    /** Protocol majors the extension supports. */
+    protocolVersions: number[];
+    /** Feature flags so the SDK can degrade gracefully. */
+    capabilities: string[];
+}
+interface PickParams {
+    /** Request resolution of elements inside iframes (may be reported unsupported in v1). */
+    iframe?: boolean;
+    /**
+     * Screenshot to include in the result. A {@link ScreenshotMode}, or a boolean for
+     * compatibility (`true` → "element", `false` → "none"). Defaults to "none".
+     */
+    screenshot?: ScreenshotMode | boolean;
+    /**
+     * The URL to pick in. The extension opens it in a tab, the user picks there, and
+     * the result is routed back to the calling tab (cross-tab picking). Required: an
+     * extension earns its keep by crossing the tab/origin boundary — a page can
+     * already script its own DOM, so same-tab picking is not an SDK capability (only
+     * the toolbar offers it, for humans). Requires the "openUrl" capability.
+     */
+    url: string;
+    /**
+     * Optional opaque identifier for "which task" this pick is for. Only used to
+     * decide whether a follow-up cross-tab pick reuses the existing target tab or
+     * opens a new one (equality compare; never interpreted). See DESIGN.md §5d.
+     */
+    key?: string;
+    /** Display-only application name, surfaced in the consent prompt. Never trusted. */
+    appName?: string;
+    /**
+     * Initial selector-generation rules for this pick (also the values shown in the
+     * gear). Composed (AND) with the user's saved rules — both can only narrow.
+     * Omitted dimensions use openpicker's defaults.
+     */
+    selector?: SelectorConfig;
+    /** Open the gear settings read-only (the user can see them but not change). Default: false. */
+    lockSelectorSettings?: boolean;
+    /** Make the selector field read-only (no hand-editing). Default: false. */
+    lockSelectorEdit?: boolean;
+    /** Only allow confirming (OK) when the selector matches exactly one element. Default: false. */
+    requireUniqueMatch?: boolean;
+}
+interface PickedElement {
+    tag: string;
+    id?: string;
+    classes?: string[];
+    text?: string;
+    attributes?: Record<string, string>;
+}
+interface PickResult {
+    /** The chosen CSS selector. */
+    selector: string;
+    /** How many elements the selector currently matches. */
+    matchCount: number;
+    /** A summary of the selected element. */
+    element: PickedElement;
+    /** Present only when `screenshot` was requested. */
+    screenshot?: string;
+}
+type CancelParams = Record<string, never>;
+type CancelResult = Record<string, never>;
+interface HighlightParams {
+    selector: string;
+}
+interface HighlightResult {
+    matchCount: number;
+}
+type ClearHighlightParams = Record<string, never>;
+type ClearHighlightResult = Record<string, never>;
+type ActivateSelfParams = Record<string, never>;
+type ActivateSelfResult = Record<string, never>;
+type IsTargetOpenParams = Record<string, never>;
+interface IsTargetOpenResult {
+    /** Whether a cross-tab target tab opened by this source is still open. */
+    open: boolean;
+}
+/** Maps each method name to its request params and response result. */
+interface MethodMap {
+    ping: {
+        params: PingParams;
+        result: PingResult;
+    };
+    pick: {
+        params: PickParams;
+        result: PickResult;
+    };
+    cancel: {
+        params: CancelParams;
+        result: CancelResult;
+    };
+    highlight: {
+        params: HighlightParams;
+        result: HighlightResult;
+    };
+    clearHighlight: {
+        params: ClearHighlightParams;
+        result: ClearHighlightResult;
+    };
+    /** Bring the calling tab to the foreground (it can only focus itself). */
+    activateSelf: {
+        params: ActivateSelfParams;
+        result: ActivateSelfResult;
+    };
+    /** Report whether the cross-tab target opened by this source is still open. */
+    isTargetOpen: {
+        params: IsTargetOpenParams;
+        result: IsTargetOpenResult;
+    };
+}
+type MethodName = keyof MethodMap;
+
+/** A method call: SDK → extension. See PROTOCOL.md §3. */
+interface RequestEnvelope<M extends MethodName = MethodName> {
+    channel: Channel;
+    v: number;
+    kind: "req";
+    id: string;
+    method: M;
+    params: MethodMap[M]["params"];
+}
+/** A reply to a request: extension → SDK. `id` echoes the request. */
+interface ResponseEnvelope<M extends MethodName = MethodName> {
+    channel: Channel;
+    v: number;
+    kind: "res";
+    id: string;
+    ok: boolean;
+    result?: MethodMap[M]["result"];
+    error?: ProtocolError;
+}
+/** Reserved notification names (none required in v1). See PROTOCOL.md §6.6. */
+type EventName = "hoverChange" | "consentChange";
+/** A fire-and-forget notification, not correlated to a single request. */
+interface EventEnvelope {
+    channel: Channel;
+    v: number;
+    kind: "evt";
+    event: EventName;
+    data: unknown;
+}
+type Envelope = RequestEnvelope | ResponseEnvelope | EventEnvelope;
+/** Narrowing guard: is this an openpicker envelope at all? */
+declare function isEnvelope(value: unknown): value is Envelope;
+
+/**
+ * Tokenize a CSS selector for syntax highlighting and for validating a selector
+ * against a {@link SelectorConfig}. Best-effort and resilient: anything
+ * unrecognized falls through as "punctuation", so an in-progress or invalid
+ * selector still tokenizes without throwing. Invariant: the concatenated token text
+ * always equals the input exactly. Lives in the protocol package so both the
+ * extension (highlighting) and the SDK (validation) can share it.
+ */
+type SelectorTokenType = "tag" | "id" | "class" | "attrName" | "attrValue" | "pseudo" | "combinator" | "punctuation";
+interface SelectorToken {
+    text: string;
+    type: SelectorTokenType;
+}
+declare function tokenizeSelector(selector: string): SelectorToken[];
+/**
+ * Whether a CSS selector only uses anchors permitted by a {@link SelectorConfig} —
+ * the SDK-side check a developer runs on the returned selector (which the user may
+ * have hand-edited). Combinators, pseudo-classes, attribute values, and the
+ * universal `*` are unconstrained. A selector touching no constrained anchors passes.
+ */
+declare function matchesSelectorConfig(selector: string, config: SelectorConfig): boolean;
+
+export { type ActivateSelfParams, type ActivateSelfResult, CHANNEL, type CancelParams, type CancelResult, type Channel, type ClearHighlightParams, type ClearHighlightResult, type Envelope, type ErrorCode, type EventEnvelope, type EventName, type HighlightParams, type HighlightResult, type IsTargetOpenParams, type IsTargetOpenResult, type MessageKind, type MethodMap, type MethodName, PROTOCOL_VERSION, type PickParams, type PickResult, type PickedElement, type PingParams, type PingResult, type ProtocolError, type RegexSource, type RequestEnvelope, type ResponseEnvelope, type ScreenshotMode, type SelectorAnchorConfig, type SelectorConfig, type SelectorToken, type SelectorTokenType, isEnvelope, matchesSelectorConfig, tokenizeSelector };

package/dist/index.js

@@ -0,0 +1,147 @@
+// src/constants.ts
+var CHANNEL = "openpicker";
+var PROTOCOL_VERSION = 1;
+
+// src/envelope.ts
+function isEnvelope(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  return v.channel === CHANNEL && typeof v.kind === "string";
+}
+
+// src/selectorTokens.ts
+var WORD = /[\w-]/;
+function tokenizeSelector(selector) {
+  const tokens = [];
+  const n = selector.length;
+  let i = 0;
+  const push = (text, type) => {
+    if (text) tokens.push({ text, type });
+  };
+  const runOfWord = (from) => {
+    let j = from;
+    while (j < n && WORD.test(selector.charAt(j))) j++;
+    return j;
+  };
+  while (i < n) {
+    const c = selector.charAt(i);
+    if (/\s/.test(c)) {
+      let j = i + 1;
+      while (j < n && /\s/.test(selector.charAt(j))) j++;
+      push(selector.slice(i, j), "combinator");
+      i = j;
+      continue;
+    }
+    if (c === ">" || c === "+" || c === "~") {
+      push(c, "combinator");
+      i++;
+      continue;
+    }
+    if (c === "#") {
+      const j = runOfWord(i + 1);
+      push(selector.slice(i, j), "id");
+      i = j;
+      continue;
+    }
+    if (c === ".") {
+      const j = runOfWord(i + 1);
+      push(selector.slice(i, j), "class");
+      i = j;
+      continue;
+    }
+    if (c === ":") {
+      let j = i + 1;
+      if (selector.charAt(j) === ":") j++;
+      j = runOfWord(j);
+      if (selector.charAt(j) === "(") {
+        let depth = 0;
+        while (j < n) {
+          const ch = selector.charAt(j);
+          j++;
+          if (ch === "(") depth++;
+          else if (ch === ")") {
+            depth--;
+            if (depth === 0) break;
+          }
+        }
+      }
+      push(selector.slice(i, j), "pseudo");
+      i = j;
+      continue;
+    }
+    if (c === "[") {
+      push("[", "punctuation");
+      i++;
+      i = (() => {
+        const nameEnd = runOfWord(i);
+        push(selector.slice(i, nameEnd), "attrName");
+        let k = nameEnd;
+        while (k < n && selector.charAt(k) !== "]") {
+          const ch = selector.charAt(k);
+          if (ch === '"' || ch === "'") {
+            let q = k + 1;
+            while (q < n && selector.charAt(q) !== ch) q++;
+            if (q < n) q++;
+            push(selector.slice(k, q), "attrValue");
+            k = q;
+          } else if (/[\s~|^$*=]/.test(ch)) {
+            push(ch, "punctuation");
+            k++;
+          } else {
+            let v = k;
+            while (v < n && !/[\]\s=~|^$*'"]/.test(selector.charAt(v))) v++;
+            push(selector.slice(k, v), "attrValue");
+            k = v;
+          }
+        }
+        return k;
+      })();
+      if (i < n && selector.charAt(i) === "]") {
+        push("]", "punctuation");
+        i++;
+      }
+      continue;
+    }
+    if (c === "*") {
+      push("*", "tag");
+      i++;
+      continue;
+    }
+    if (WORD.test(c)) {
+      const j = runOfWord(i);
+      push(selector.slice(i, j), "tag");
+      i = j;
+      continue;
+    }
+    push(c, "punctuation");
+    i++;
+  }
+  return tokens;
+}
+function anchorAllowsName(name, anchor) {
+  if (!anchor) return true;
+  if (anchor.enabled === false) return false;
+  try {
+    if (anchor.ignore && new RegExp(anchor.ignore).test(name)) return false;
+    if (anchor.allow) return new RegExp(anchor.allow).test(name);
+  } catch {
+    return true;
+  }
+  return true;
+}
+function matchesSelectorConfig(selector, config) {
+  for (const tok of tokenizeSelector(selector)) {
+    if (tok.type === "id") {
+      if (!anchorAllowsName(tok.text.replace(/^#/, ""), config.id)) return false;
+    } else if (tok.type === "class") {
+      if (!anchorAllowsName(tok.text.replace(/^\./, ""), config.class)) return false;
+    } else if (tok.type === "tag") {
+      if (tok.text !== "*" && !anchorAllowsName(tok.text, config.tag)) return false;
+    } else if (tok.type === "attrName") {
+      if (!anchorAllowsName(tok.text, config.attr)) return false;
+    }
+  }
+  return true;
+}
+
+export { CHANNEL, PROTOCOL_VERSION, isEnvelope, matchesSelectorConfig, tokenizeSelector };

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@openpicker/protocol",
+  "version": "0.1.0",
+  "description": "Open postMessage protocol for the openpicker CSS element picker — wire types, constants, and selector helpers.",
+  "license": "MIT",
+  "author": "Usertour (https://www.usertour.io)",
+  "homepage": "https://openpicker.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/usertour/openpicker.git",
+    "directory": "packages/protocol"
+  },
+  "bugs": {
+    "url": "https://github.com/usertour/openpicker/issues"
+  },
+  "keywords": [
+    "openpicker",
+    "protocol",
+    "postmessage",
+    "element-picker",
+    "css-selector",
+    "browser-extension"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js"
+}