@omercnet/paseo-queens 0.1.0-next.126.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Omer Cohen
+
+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,122 @@
+# Queens
+
+A cross-platform Queens logic game for Paseo. Play from the global sidebar or open the compact composer mini-game while agents work in the background.
+
+## Screenshots
+
+These screenshots use synthetic workspace and agent names on an isolated Paseo daemon.
+
+### Full game
+
+![Queens full game with an 8×8 puzzle](https://raw.githubusercontent.com/omercnet/paseo-plugins/main/queens/docs/images/queens-wide.png)
+
+### Compact 14×14 board
+
+![Queens compact layout with a 14×14 hard puzzle](https://raw.githubusercontent.com/omercnet/paseo-plugins/main/queens/docs/images/queens-compact.png)
+
+### Composer mini-game
+
+![Queens composer pill and playable popover](https://raw.githubusercontent.com/omercnet/paseo-plugins/main/queens/docs/images/queens-composer.png)
+
+## What it does
+
+- Provides a global **Queens** sidebar surface and Command Center entry.
+- Adds a **Queens** composer pill to every active agent.
+- Opens a playable anchored popover on wide layouts and a compact sheet on mobile.
+- Supports 5×5 through 14×14 boards at Beginner, Easy, Medium, and Hard levels.
+- Stores progress, completion records, selected size, and difficulty in host-scoped settings.
+- Shares progress and undo history between the full surface and composer mini-game.
+- Shows the number of running agents and notifies you when they all become idle.
+
+## How to play
+
+Place exactly one queen in every row, column, and colored region. Queens may not touch, including diagonally.
+
+- Tap or click once to place or remove an X.
+- Double-tap or double-click to place or remove a queen.
+- Drag from an empty square to mark multiple Xs.
+- Drag from an X to erase multiple Xs.
+- Use **Hint**, **Undo**, and **Reset** when needed.
+
+## Puzzle catalog
+
+The catalog contains 97,184 curated puzzles across 40 size and difficulty combinations. Puzzle layouts, classifications, and solutions are sourced from the public [Queens Ultimate](https://queensultimate.com/) puzzle corpus.
+
+The compact groups live in an unlisted, revision-pinned [GitHub Gist](https://gist.github.com/omercnet/652af12e2640979ba7fb5dc5adddde42). The Paseo daemon fetches only the selected group, verifies its SHA-256 digest, and caches it for the session. Opening a size and difficulty for the first time therefore requires network access to `gist.githubusercontent.com`.
+
+The importer validates every public index and source chunk, then writes the 40 upload payloads and a manifest to `/tmp/queens-curated-gist` by default:
+
+```bash
+npm run import:puzzles
+```
+
+After uploading those files to an unlisted Gist, regenerate the pinned runtime manifest with the immutable Gist revision:
+
+```bash
+QUEENS_GIST_ID=<gist-id> \
+QUEENS_GIST_REVISION=<revision-sha> \
+npm run import:puzzles
+```
+
+## Install
+
+### Paseo 0.9 beta
+
+Install the published npm package on the daemon host:
+
+```bash
+paseo plugin install npm:@omercnet/paseo-queens
+```
+
+Update an npm installation:
+
+```bash
+paseo plugin update queens --check
+paseo plugin update queens
+```
+
+### Paseo 0.8
+
+Install from this monorepo:
+
+```bash
+paseo plugin install omercnet/paseo-plugins:queens
+```
+
+Or install a local checkout by absolute path on the daemon host:
+
+```bash
+paseo plugin install /absolute/path/to/paseo-plugins/queens
+```
+
+Open **Queens** from the sidebar or Command Center. Open any agent session to use the composer mini-game.
+
+## Develop
+
+Use an isolated Paseo home and explicit host. Never reload this development checkout against your default daemon.
+
+```bash
+npm ci
+npm run check
+npm run typecheck
+npm test
+
+paseo daemon config set daemon.listen 127.0.0.1:6802 --home /tmp/queens-dev
+paseo daemon config set daemon.relay.enabled false --home /tmp/queens-dev
+paseo daemon config set features.webUi.enabled true --home /tmp/queens-dev
+paseo daemon config set pluginsEnabled true --home /tmp/queens-dev
+paseo daemon start --home /tmp/queens-dev
+paseo plugin install "$PWD" --host 127.0.0.1:6802
+```
+
+Release Please owns package versions, changelog generation, component tags, and GitHub releases.
+
+## Requirements
+
+- Paseo `^0.8.0` or `^0.9.0-beta.1`
+- Plugins enabled on the target daemon
+- React Native-compatible Paseo client on web, desktop, iOS, or Android
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/client/completion-feedback.tsx

@@ -0,0 +1,55 @@
+import type { ReactNode } from "react";
+import { type StyleProp, StyleSheet, View, type ViewStyle } from "react-native";
+
+export type CompletionFeedbackProps = {
+  solved: boolean;
+  color: string;
+  children: ReactNode;
+  style?: StyleProp<ViewStyle>;
+};
+
+/**
+ * Adds a static, non-interactive solved-state illumination around existing content.
+ * Keeping this to core View primitives makes the surface safe in every plugin runtime.
+ */
+export function CompletionFeedback({ solved, color, children, style }: CompletionFeedbackProps) {
+  return (
+    <View style={[styles.container, style]}>
+      {children}
+      {solved ? (
+        <View
+          pointerEvents="none"
+          accessible={false}
+          accessibilityElementsHidden
+          importantForAccessibility="no-hide-descendants"
+          style={styles.overlay}
+        >
+          <View style={[styles.tint, { backgroundColor: color }]} />
+          <View style={[styles.outline, { borderColor: color }]} />
+        </View>
+      ) : null}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    position: "relative",
+    overflow: "hidden",
+    borderRadius: 14,
+  },
+  overlay: {
+    ...StyleSheet.absoluteFillObject,
+    borderRadius: 14,
+  },
+  tint: {
+    ...StyleSheet.absoluteFillObject,
+    opacity: 0.055,
+  },
+  outline: {
+    ...StyleSheet.absoluteFillObject,
+    borderWidth: 2,
+    borderRadius: 14,
+    opacity: 0.34,
+  },
+});

package/client/composer-pill.tsx

@@ -0,0 +1,74 @@
+import type { PluginClientContext } from "@getpaseo/plugin/client";
+import { QueenPillIcon, QueensPopover } from "./queens-popover";
+
+const PAGE_LIMIT = 200;
+const MAX_PAGES = 10;
+
+type AgentTarget = {
+  readonly id: string;
+  readonly workspaceId?: string | null;
+  readonly status: string;
+  readonly archivedAt?: string | null;
+};
+
+export function registerQueensComposerPills(client: PluginClientContext) {
+  const pills = new Map<string, { workspaceId: string; remove(): void }>();
+  let stopped = false;
+
+  const removePill = (agentId: string) => {
+    pills.get(agentId)?.remove();
+    pills.delete(agentId);
+  };
+
+  const syncAgent = (agent: AgentTarget) => {
+    if (!agent.workspaceId || agent.archivedAt || agent.status === "closed") {
+      removePill(agent.id);
+      return;
+    }
+
+    const current = pills.get(agent.id);
+    if (current?.workspaceId === agent.workspaceId) return;
+    removePill(agent.id);
+    const pill = client.addComposerPill({
+      id: "queens",
+      workspaceId: agent.workspaceId,
+      agentId: agent.id,
+      button: {
+        title: "Queens",
+        label: "Queens",
+        icon: QueenPillIcon,
+        behavior: { kind: "popover", Content: QueensPopover },
+      },
+    });
+    pills.set(agent.id, { workspaceId: agent.workspaceId, remove: pill.remove });
+  };
+
+  const unsubscribe = client.paseo.agents.subscribe((update) => {
+    if (update.kind === "remove") {
+      removePill(update.agentId);
+      return;
+    }
+    syncAgent(update.agent);
+  });
+
+  void (async () => {
+    let cursor: string | undefined;
+    for (let page = 0; page < MAX_PAGES; page += 1) {
+      const result = await client.paseo.agents.list({
+        sort: [{ key: "updated_at", direction: "desc" }],
+        page: { limit: PAGE_LIMIT, ...(cursor ? { cursor } : {}) },
+      });
+      if (stopped) return;
+      for (const { agent } of result.entries) syncAgent(agent);
+      cursor = result.pageInfo.hasMore ? (result.pageInfo.nextCursor ?? undefined) : undefined;
+      if (!cursor) return;
+    }
+  })().catch(() => undefined);
+
+  return () => {
+    stopped = true;
+    unsubscribe();
+    for (const pill of pills.values()) pill.remove();
+    pills.clear();
+  };
+}

package/client/contribute.tsx

@@ -0,0 +1,34 @@
+import type { PluginClientContext } from "@getpaseo/plugin/client";
+import { registerQueensComposerPills } from "./composer-pill";
+import { PaseoQueensSurface } from "./queens-surface";
+import { disposePersistedGames } from "./use-persisted-game";
+
+export function registerPaseoQueensClient(client: PluginClientContext) {
+  const cleanups = [
+    disposePersistedGames,
+    client.addSurface("queens", PaseoQueensSurface),
+    registerQueensComposerPills(client),
+    client.addSidebarItem({
+      id: "queens",
+      title: "Queens",
+      icon: "Crown",
+      surface: "queens",
+    }),
+    client.addCommandCenterItem({
+      id: "open-queens",
+      title: "Open Queens",
+      icon: "Crown",
+      keywords: ["queens", "logic", "puzzle", "game"],
+      context: "global",
+      onSelect({ openSurface }) {
+        openSurface("queens");
+      },
+    }),
+  ];
+
+  return () => {
+    for (const cleanup of cleanups.reverse()) cleanup();
+  };
+}
+
+export default registerPaseoQueensClient;

package/client/game/curated.ts

@@ -0,0 +1,91 @@
+import type { PuzzleDifficulty } from "../../shared/puzzle-catalog";
+import type { Puzzle } from "./types";
+
+export type EncodedPuzzleDeck = {
+  readonly size: number;
+  readonly difficulty: PuzzleDifficulty;
+  readonly count: number;
+  readonly recordBytes: number;
+  readonly data: string;
+};
+
+export type CuratedPuzzleDeck = {
+  readonly key: string;
+  readonly size: number;
+  readonly difficulty: PuzzleDifficulty;
+  readonly puzzles: readonly Puzzle[];
+  readonly solutions: Readonly<Record<string, readonly number[]>>;
+};
+
+const BASE64_VALUES = new Int16Array(128);
+BASE64_VALUES.fill(-1);
+for (let index = 0; index < 26; index += 1) {
+  BASE64_VALUES[65 + index] = index;
+  BASE64_VALUES[97 + index] = index + 26;
+}
+for (let index = 0; index < 10; index += 1) BASE64_VALUES[48 + index] = index + 52;
+BASE64_VALUES[43] = 62;
+BASE64_VALUES[47] = 63;
+
+function decodeBase64(encoded: string): Uint8Array {
+  const padding = encoded.endsWith("==") ? 2 : encoded.endsWith("=") ? 1 : 0;
+  const output = new Uint8Array((encoded.length * 3) / 4 - padding);
+  let accumulator = 0;
+  let bits = 0;
+  let outputIndex = 0;
+  for (let index = 0; index < encoded.length; index += 1) {
+    const code = encoded.charCodeAt(index);
+    if (code === 61) break;
+    const value = code < BASE64_VALUES.length ? BASE64_VALUES[code] : -1;
+    if (value < 0) throw new RangeError("Curated puzzle data contains invalid base64.");
+    accumulator = (accumulator << 6) | value;
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      output[outputIndex] = (accumulator >> bits) & 255;
+      outputIndex += 1;
+    }
+  }
+  if (outputIndex !== output.length) throw new RangeError("Curated puzzle data is truncated.");
+  return output;
+}
+
+export function decodePuzzleDeck(encoded: EncodedPuzzleDeck): CuratedPuzzleDeck {
+  const key = `${encoded.size}-${encoded.difficulty}`;
+
+  const bytes = decodeBase64(encoded.data);
+  if (bytes.length !== encoded.count * encoded.recordBytes) {
+    throw new RangeError(`Curated ${key} deck has an invalid byte length.`);
+  }
+
+  const regionBytes = Math.ceil((encoded.size * encoded.size) / 2);
+  const expectedRecordBytes = 2 + regionBytes + encoded.size;
+  if (encoded.recordBytes !== expectedRecordBytes) {
+    throw new RangeError(`Curated ${key} deck has an invalid record size.`);
+  }
+
+  const puzzles: Puzzle[] = [];
+  const solutions: Record<string, readonly number[]> = {};
+  for (let record = 0; record < encoded.count; record += 1) {
+    let offset = record * encoded.recordBytes;
+    const sourceId = (bytes[offset] << 8) | bytes[offset + 1];
+    offset += 2;
+    const id = `queens-${encoded.size}x${encoded.size}-${encoded.difficulty}-${sourceId}`;
+    const regions = Array<number>(encoded.size * encoded.size);
+    for (let cell = 0; cell < regions.length; cell += 2) {
+      const packed = bytes[offset + Math.floor(cell / 2)];
+      regions[cell] = packed >> 4;
+      if (cell + 1 < regions.length) regions[cell + 1] = packed & 15;
+    }
+    offset += regionBytes;
+    const solution = Array<number>(encoded.size);
+    for (let row = 0; row < encoded.size; row += 1) {
+      solution[row] = row * encoded.size + bytes[offset + row];
+    }
+    puzzles.push({ id, size: encoded.size, regions });
+    solutions[id] = solution;
+  }
+
+  const deck = { key, size: encoded.size, difficulty: encoded.difficulty, puzzles, solutions };
+  return deck;
+}

package/client/game/engine.ts

@@ -0,0 +1,199 @@
+import type { CellState, Puzzle } from "./types";
+
+function assertSize(size: number): void {
+  if (!Number.isInteger(size) || size < 1) {
+    throw new RangeError("Board size must be a positive integer.");
+  }
+}
+
+function assertPuzzle(puzzle: Puzzle): void {
+  assertSize(puzzle.size);
+
+  const expectedCellCount = puzzle.size * puzzle.size;
+  if (puzzle.regions.length !== expectedCellCount) {
+    throw new RangeError(`Puzzle must contain exactly ${expectedCellCount} region cells.`);
+  }
+
+  const regions = new Set<number>();
+  for (const region of puzzle.regions) {
+    if (!Number.isInteger(region) || region < 0 || region >= puzzle.size) {
+      throw new RangeError(`Region ids must be integers from 0 to ${puzzle.size - 1}.`);
+    }
+    regions.add(region);
+  }
+
+  if (regions.size !== puzzle.size) {
+    throw new RangeError(`Puzzle must contain all ${puzzle.size} region ids.`);
+  }
+}
+
+function assertCells(puzzle: Puzzle, cells: readonly CellState[]): void {
+  const expectedCellCount = puzzle.size * puzzle.size;
+  if (cells.length !== expectedCellCount) {
+    throw new RangeError(`Board must contain exactly ${expectedCellCount} cells.`);
+  }
+}
+
+export function createEmptyCells(size: number): CellState[] {
+  assertSize(size);
+  return Array.from({ length: size * size }, () => "empty" as const);
+}
+
+export function setCellStates(
+  cells: readonly CellState[],
+  indexes: readonly number[],
+  state: CellState,
+): readonly CellState[] {
+  let next: CellState[] | null = null;
+  for (const index of indexes) {
+    if (!Number.isInteger(index) || index < 0 || index >= cells.length) {
+      throw new RangeError("Cell index is outside the board.");
+    }
+    if (cells[index] === state) continue;
+
+    next ??= cells.slice();
+    next[index] = state;
+  }
+  return next ?? cells;
+}
+
+function addGroupConflicts(
+  groups: ReadonlyMap<number, readonly number[]>,
+  conflicts: Set<number>,
+): void {
+  for (const indexes of groups.values()) {
+    if (indexes.length > 1) {
+      for (const index of indexes) conflicts.add(index);
+    }
+  }
+}
+function addToGroup(groups: Map<number, number[]>, key: number, index: number): void {
+  const group = groups.get(key);
+  if (group) group.push(index);
+  else groups.set(key, [index]);
+}
+
+export function findConflicts(puzzle: Puzzle, cells: readonly CellState[]): Set<number> {
+  assertPuzzle(puzzle);
+  assertCells(puzzle, cells);
+
+  const { size } = puzzle;
+  const markedIndexes: number[] = [];
+  const rows = new Map<number, number[]>();
+  const columns = new Map<number, number[]>();
+  const regions = new Map<number, number[]>();
+
+  for (let index = 0; index < cells.length; index += 1) {
+    if (cells[index] !== "marked") continue;
+
+    markedIndexes.push(index);
+    const row = Math.floor(index / size);
+    const column = index % size;
+    const region = puzzle.regions[index];
+    addToGroup(rows, row, index);
+    addToGroup(columns, column, index);
+    addToGroup(regions, region, index);
+  }
+
+  const conflicts = new Set<number>();
+  addGroupConflicts(rows, conflicts);
+  addGroupConflicts(columns, conflicts);
+  addGroupConflicts(regions, conflicts);
+
+  const marked = new Set(markedIndexes);
+  for (const index of markedIndexes) {
+    const row = Math.floor(index / size);
+    const column = index % size;
+
+    for (let rowOffset = -1; rowOffset <= 1; rowOffset += 1) {
+      for (let columnOffset = -1; columnOffset <= 1; columnOffset += 1) {
+        if (rowOffset === 0 && columnOffset === 0) continue;
+
+        const adjacentRow = row + rowOffset;
+        const adjacentColumn = column + columnOffset;
+        if (
+          adjacentRow < 0 ||
+          adjacentRow >= size ||
+          adjacentColumn < 0 ||
+          adjacentColumn >= size
+        ) {
+          continue;
+        }
+
+        const adjacentIndex = adjacentRow * size + adjacentColumn;
+        if (marked.has(adjacentIndex)) {
+          conflicts.add(index);
+          conflicts.add(adjacentIndex);
+        }
+      }
+    }
+  }
+
+  return conflicts;
+}
+
+export function isSolved(puzzle: Puzzle, cells: readonly CellState[]): boolean {
+  const conflicts = findConflicts(puzzle, cells);
+
+  let markedCount = 0;
+  const markedRows = new Set<number>();
+  const markedColumns = new Set<number>();
+  const markedRegions = new Set<number>();
+
+  for (let index = 0; index < cells.length; index += 1) {
+    if (cells[index] !== "marked") continue;
+    markedCount += 1;
+    markedRows.add(Math.floor(index / puzzle.size));
+    markedColumns.add(index % puzzle.size);
+    markedRegions.add(puzzle.regions[index]);
+  }
+
+  return (
+    markedCount === puzzle.size &&
+    markedRows.size === puzzle.size &&
+    markedColumns.size === puzzle.size &&
+    markedRegions.size === puzzle.size &&
+    conflicts.size === 0
+  );
+}
+
+export function countSolutions(puzzle: Puzzle, limit = Number.POSITIVE_INFINITY): number {
+  assertPuzzle(puzzle);
+  if (limit !== Number.POSITIVE_INFINITY && (!Number.isInteger(limit) || limit < 0)) {
+    throw new RangeError("Solution limit must be a non-negative integer or Infinity.");
+  }
+  if (limit === 0) return 0;
+
+  const { size } = puzzle;
+  const usedColumns = new Uint8Array(size);
+  const usedRegions = new Uint8Array(size);
+  let solutions = 0;
+
+  function search(row: number, previousColumn: number): void {
+    if (solutions >= limit) return;
+    if (row === size) {
+      solutions += 1;
+      return;
+    }
+
+    for (let column = 0; column < size; column += 1) {
+      const region = puzzle.regions[row * size + column];
+      if (
+        usedColumns[column] === 1 ||
+        usedRegions[region] === 1 ||
+        (row > 0 && Math.abs(column - previousColumn) <= 1)
+      ) {
+        continue;
+      }
+
+      usedColumns[column] = 1;
+      usedRegions[region] = 1;
+      search(row + 1, column);
+      usedColumns[column] = 0;
+      usedRegions[region] = 0;
+    }
+  }
+
+  search(0, -2);
+  return solutions;
+}

package/client/game/index.ts

@@ -0,0 +1,5 @@
+export { countSolutions, createEmptyCells, findConflicts, isSolved, setCellStates } from "./engine";
+export { PUZZLES } from "./puzzles";
+export type { GameAction, GameState, PuzzleProgress, PuzzleSolution, TimerState } from "./state";
+export { createGameState, gameReducer } from "./state";
+export type { CellState, Puzzle } from "./types";