@tapcue/extension-sdk 0.1.0

package/src/overlay-jsx-runtime.ts

@@ -0,0 +1,72 @@
+/**
+ * The overlay's automatic-JSX factory. A file with `@jsxImportSource @tapcue/extension-sdk/overlay`
+ * compiles `<G/>` through here into an `SvgNode` (capabilities.ts) — a separate JSX world from the
+ * view runtime, so `JSX.Element` is `SvgNode`, and `overlay.draw([<G/>])` type-checks with no cast.
+ * Props are literal wire values (numbers, colours, a `translate($pointer)` string), so the factory
+ * only reshapes them into `{ tag, … }`; the bytes are what a hand-written `SvgNode` produced.
+ */
+
+import type { SvgNode } from "./capabilities.js";
+
+const FRAGMENT_TAG = "__fragment";
+
+function isSvgNode(value: unknown): value is SvgNode {
+  return typeof value === "object" && value !== null && typeof (value as { tag?: unknown }).tag === "string";
+}
+
+function normalizeChildren(children: unknown): SvgNode[] {
+  const out: SvgNode[] = [];
+  const visit = (child: unknown): void => {
+    if (child === null || child === undefined || child === false || child === true) return;
+    if (Array.isArray(child)) {
+      for (const nested of child) visit(nested);
+      return;
+    }
+    if (isSvgNode(child)) {
+      if ((child as { tag: string }).tag === FRAGMENT_TAG) {
+        visit((child as unknown as { children?: unknown }).children);
+        return;
+      }
+      out.push(child);
+    }
+  };
+  visit(children);
+  return out;
+}
+
+function createSvg(type: unknown, rawProps: Record<string, unknown> | null): SvgNode {
+  const props = rawProps ?? {};
+  const svgTag = (type as { __svgTag?: string }).__svgTag;
+  if (typeof svgTag !== "string") {
+    throw new Error("overlay JSX accepts only the exported SVG primitive components");
+  }
+  if (svgTag === FRAGMENT_TAG) {
+    return { tag: FRAGMENT_TAG, children: normalizeChildren(props.children) } as unknown as SvgNode;
+  }
+  const { children, ...rest } = props;
+  const node: Record<string, unknown> = { tag: svgTag, ...rest };
+  // `g` is the only container; every leaf carries its geometry in props alone.
+  if (svgTag === "g") node.children = normalizeChildren(children);
+  return node as unknown as SvgNode;
+}
+
+export function jsx(type: unknown, props: Record<string, unknown>): SvgNode {
+  return createSvg(type, props);
+}
+
+export const jsxs = jsx;
+
+export function jsxDEV(type: unknown, props: Record<string, unknown>): SvgNode {
+  return createSvg(type, props);
+}
+
+export const Fragment: { __svgTag: string } = { __svgTag: FRAGMENT_TAG };
+
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export namespace JSX {
+  export type Element = SvgNode;
+  export interface ElementChildrenAttribute {
+    children: Record<string, never>;
+  }
+  export type IntrinsicElements = Record<string, never>;
+}

package/src/overlay.ts

@@ -0,0 +1,130 @@
+/**
+ * JSX authoring for the overlay's SVG subset (capabilities.ts `SvgNode`).
+ *
+ * The host ships the **primitives** — the SVG contract — never a component library: an SDK that
+ * shipped `Magnifier()` / `Ruler()` would be betting on what extensions draw, the same mistake as
+ * a `pick.color` verb one layer up. So these are the seven tags and nothing semantic; a loupe or a
+ * ruler is thirty lines that live in the extension that wants one, built from these.
+ *
+ * Author with a per-file pragma so `<G/>` compiles to an `SvgNode`, not a view node:
+ *
+ *     /** @jsxImportSource @tapcue/extension-sdk/overlay *\/
+ *     import { G, Rect, translate, pointer } from "@tapcue/extension-sdk/overlay";
+ *     const ruler = <G transform={translate(pointer)}>…</G>;   // ruler: SvgNode
+ *
+ * The live bindings (`translate(pointer)`, `pointerColor`, `livePointer`) are typed sugar over the
+ * exact strings the shell resolves every frame with no IPC — the wire is byte-for-byte what a hand
+ * written `SvgNode` produced, so the host renderer is unchanged.
+ */
+
+import type { CircleClip, ImageSource, Point, SvgNode, Transform } from "./capabilities.js";
+
+// ── Live bindings (the shell resolves these every frame, locally, with no isolate wake) ──────────
+
+/** The live cursor position. Pass to `translate` to glue a subtree to the pointer. */
+export const pointer: unique symbol = Symbol.for("tapcue.overlay.pointer") as never;
+
+/** `translate(pointer)` → the live binding; `translate({x,y})` → a fixed offset. */
+export function translate(target: typeof pointer | Point): Transform {
+  return target === pointer ? "translate($pointer)" : `translate(${target.x} ${target.y})`;
+}
+export function scale(k: number): Transform {
+  return `scale(${k})`;
+}
+export function rotate(degrees: number): Transform {
+  return `rotate(${degrees})`;
+}
+
+/** The live pixel colour under the cursor. Use as a `fill`, `stroke`, or `<Text text>` value. */
+export const pointerColor = "$pointerColor";
+
+/** The magnified screen around the cursor, resolved by the shell every frame — no pixel ever
+ *  enters the isolate. Use as an `<OverlayImage href>`. */
+export function livePointer(width: number, height: number): ImageSource {
+  return { live: "pointer", width, height };
+}
+
+// ── SVG primitive components (compile to `SvgNode` via overlay-jsx-runtime.ts) ───────────────────
+
+type SvgChild = SvgNode | SvgNode[] | false | null | undefined;
+type SvgChildren = SvgChild | SvgChild[];
+
+interface Tag<P> {
+  (props: P): SvgNode;
+  readonly __svgTag: string;
+}
+function tag<P>(name: string): Tag<P> {
+  const component = ((_props: P) => ({ tag: name }) as SvgNode) as Tag<P> & { __svgTag: string };
+  component.__svgTag = name;
+  return component;
+}
+
+export interface GProps {
+  transform?: Transform;
+  opacity?: number;
+  clip?: CircleClip;
+  children?: SvgChildren;
+}
+export interface RectProps {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  rx?: number;
+  fill?: string;
+  stroke?: string;
+  strokeWidth?: number;
+}
+export interface CircleProps {
+  cx: number;
+  cy: number;
+  r: number;
+  fill?: string;
+  stroke?: string;
+  strokeWidth?: number;
+}
+export interface LineProps {
+  x1: number;
+  y1: number;
+  x2: number;
+  y2: number;
+  stroke?: string;
+  strokeWidth?: number;
+  dash?: number[];
+}
+export interface PathProps {
+  d: string;
+  fill?: string;
+  stroke?: string;
+  strokeWidth?: number;
+  dash?: number[];
+}
+export interface TextProps {
+  x: number;
+  y: number;
+  text: string;
+  /**
+   * `#rrggbb`, or **`currentColor`** — the host's own label colour, resolved when the frame is
+   * drawn. A card lives in Tapcue's chrome on the user's theme, so text with a hard-coded colour
+   * is text that disappears in the other one.
+   */
+  fill?: string;
+  fontSize?: number;
+  anchor?: "start" | "middle" | "end";
+}
+export interface OverlayImageProps {
+  href: ImageSource;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  rendering?: "pixelated" | "smooth";
+}
+
+export const G = tag<GProps>("g");
+export const Rect = tag<RectProps>("rect");
+export const Circle = tag<CircleProps>("circle");
+export const Line = tag<LineProps>("line");
+export const Path = tag<PathProps>("path");
+export const Text = tag<TextProps>("text");
+export const OverlayImage = tag<OverlayImageProps>("image");

package/src/permission-units.ts

@@ -0,0 +1,109 @@
+/**
+ * The permission-unit table, as TypeScript sees it.
+ *
+ * The vocabulary itself lives in `proto/permission-units.json` — one file for all three languages
+ * (see its `$comment`). This is TypeScript's copy of it, kept as a `const` array rather than
+ * imported from the JSON because the union type below has to exist at compile time, and a JSON
+ * import widens to `string`. `tests/permission-units.test.ts` reads the JSON and asserts this
+ * matches it entry for entry, so the copy cannot drift without failing.
+ *
+ * Everything else in the SDK that needs to know the vocabulary is derived from here: the
+ * `PermissionUnit` union, `permissionUnits()`, and the boolean half of merging and intersecting
+ * two permission blocks.
+ */
+
+/** How a unit's value narrows when a declaration meets an approval. */
+export type PermissionKind =
+  | "boolean"
+  | "hosts"
+  | "quota"
+  | "names"
+  | "precision"
+  /** A list of `FileReadGrant`s — where the extension may read (spec 016 §2). */
+  | "paths"
+  /** A list of `QueryGrant`s — which stored database queries it may run. */
+  | "queries"
+  /** A list of `ExecGrant`s — which binaries it may run (spec 016 §3). */
+  | "binaries";
+
+export interface PermissionUnitSpec {
+  readonly unit: string;
+  /** The object it sits under in a permissions block. */
+  readonly group: string;
+  /** The field inside that object, or `null` when the group *is* the unit. */
+  readonly key: string | null;
+  readonly kind: PermissionKind;
+  /** The host load frame's field name, or `null` for a unit nothing enforces yet. */
+  readonly wire: string | null;
+  /** Whether an op actually checks it today. See the JSON's note on declared-but-unenforced. */
+  readonly enforced: boolean;
+}
+
+export const PERMISSION_UNITS = [
+  { unit: "http", group: "http", key: null, kind: "hosts", wire: "hosts", enforced: true },
+  { unit: "storage", group: "storage", key: null, kind: "quota", wire: "storage", enforced: true },
+  { unit: "cache", group: "cache", key: null, kind: "quota", wire: "cache", enforced: true },
+  { unit: "files.read", group: "files", key: "read", kind: "paths", wire: "filesRead", enforced: true },
+  { unit: "exec", group: "exec", key: null, kind: "binaries", wire: "exec", enforced: true },
+  { unit: "queries", group: "queries", key: null, kind: "queries", wire: "queries", enforced: true },
+  { unit: "secrets", group: "secrets", key: null, kind: "names", wire: null, enforced: false },
+  { unit: "clipboard.read", group: "clipboard", key: "read", kind: "boolean", wire: null, enforced: false },
+  { unit: "clipboard.write", group: "clipboard", key: "write", kind: "boolean", wire: "clipboardWrite", enforced: true },
+  { unit: "recents.record", group: "recents", key: "record", kind: "boolean", wire: "recentsRecord", enforced: true },
+  { unit: "recents.list", group: "recents", key: "list", kind: "boolean", wire: "recentsList", enforced: true },
+  { unit: "recents.remove", group: "recents", key: "remove", kind: "boolean", wire: "recentsRemove", enforced: true },
+  { unit: "workspace.roots", group: "workspace", key: "roots", kind: "boolean", wire: "workspaceRoots", enforced: true },
+  { unit: "context.frontmost-app", group: "context", key: "frontmostApp", kind: "boolean", wire: null, enforced: false },
+  { unit: "context.selected-text", group: "context", key: "selectedText", kind: "boolean", wire: null, enforced: false },
+  { unit: "context.selected-files", group: "context", key: "selectedFiles", kind: "boolean", wire: null, enforced: false },
+  { unit: "fonts", group: "fonts", key: null, kind: "boolean", wire: "fonts", enforced: true },
+  { unit: "location", group: "location", key: null, kind: "precision", wire: "location", enforced: true },
+  { unit: "process.list", group: "process", key: "list", kind: "boolean", wire: "process", enforced: true },
+  { unit: "process.command", group: "process", key: "command", kind: "boolean", wire: "processCommand", enforced: true },
+  { unit: "process.kill", group: "process", key: "kill", kind: "boolean", wire: "processKill", enforced: true },
+  { unit: "native.notify", group: "native", key: "notify", kind: "boolean", wire: null, enforced: false },
+  { unit: "native.save", group: "native", key: "save", kind: "boolean", wire: "nativeSave", enforced: true },
+  { unit: "screen.overlay", group: "screen", key: "overlay", kind: "boolean", wire: "screenOverlay", enforced: true },
+  { unit: "screen.capture", group: "screen", key: "capture", kind: "boolean", wire: "screenCapture", enforced: true },
+  { unit: "ui.webview", group: "ui", key: "webview", kind: "boolean", wire: "uiWebview", enforced: true },
+  { unit: "background", group: "background", key: null, kind: "boolean", wire: "background", enforced: true },
+  { unit: "suggestions.rules", group: "suggestions", key: "rules", kind: "boolean", wire: "suggestionRules", enforced: true },
+] as const satisfies readonly PermissionUnitSpec[];
+
+/**
+ * Every unit a manifest may declare.
+ *
+ * `native.open` and `native.reveal` are deliberately absent: they are action-only effects (a
+ * keystroke can reach neither), and both are low-risk — `open` launches only http/https in the
+ * browser, visible and reversible, and `reveal` only shows a file the user already handed over.
+ * They are ambient on `ActionContext`, needing no declaration and no grant, which keeps the
+ * permission list short enough to actually read. `notify` and `save` stay units: a notification is
+ * unsolicited, and `save` leaves bytes on disk.
+ */
+export type PermissionUnit = (typeof PERMISSION_UNITS)[number]["unit"];
+
+/** The units whose group/key pair is a plain boolean — the ones that merge and intersect by hand. */
+export const BOOLEAN_PERMISSION_UNITS = PERMISSION_UNITS.filter(
+  (spec): spec is Extract<(typeof PERMISSION_UNITS)[number], { kind: "boolean"; key: string }> =>
+    spec.kind === "boolean" && spec.key !== null,
+);
+
+/** Units that sit directly on a permissions block as a bare `true`, with no object around them. */
+export const FLAG_PERMISSION_UNITS = PERMISSION_UNITS.filter(
+  (spec) => spec.kind === "boolean" && spec.key === null,
+);
+
+/**
+ * The boolean units, gathered by the object they live under — `clipboard` → `read`/`write`, and so
+ * on. Merging and intersecting two permission blocks walk this rather than naming each field, so a
+ * new boolean unit is one row in the table above and nothing else.
+ */
+export const BOOLEAN_PERMISSION_GROUPS: ReadonlyMap<string, readonly string[]> = (() => {
+  const groups = new Map<string, string[]>();
+  for (const spec of BOOLEAN_PERMISSION_UNITS) {
+    const keys = groups.get(spec.group) ?? [];
+    keys.push(spec.key);
+    groups.set(spec.group, keys);
+  }
+  return groups;
+})();