@sirenodeck/sirenodeck 0.1.1-alpha.0

package/src/core/gesture-state.ts

@@ -0,0 +1,344 @@
+export const HOLD_ACTION_DELAY_MS = 200
+export const DOUBLE_TAP_DELAY_MS = 200
+
+export const SPA_HOLD_DELAY_MS = 500
+export const SPA_DOUBLE_TAP_DELAY_MS = 300
+
+export type GestureType = "down" | "up"
+
+export interface GestureEvent {
+  readonly type: GestureType
+  readonly timestamp: number
+  readonly keyIndex?: number
+}
+
+export type GestureKind = "tap" | "dbl-tap" | "hold"
+
+export interface GestureResult {
+  readonly kind: GestureKind
+  readonly keyIndex?: number
+  readonly timestamp: number
+  readonly durationMs?: number
+  readonly timestamps?: ReadonlyArray<number>
+}
+
+type KeyState =
+  | { name: "idle"; keyIndex?: number }
+  | {
+      name: "holding"
+      downAt: number
+      timer?: ReturnType<typeof setTimeout>
+      keyIndex?: number
+      emittedHold?: boolean
+    }
+  | {
+      name: "waiting-second"
+      firstUpAt: number
+      firstDownAt: number
+      timer?: ReturnType<typeof setTimeout>
+      keyIndex?: number
+    }
+  | {
+      name: "second-down"
+      secondDownAt: number
+      firstUpAt: number
+      firstDownAt: number
+      keyIndex?: number
+    }
+
+const tap = (
+  upEvent: GestureEvent,
+  downAt: number,
+  keyIndex?: number,
+): GestureResult =>
+  Object.freeze({
+    kind: "tap",
+    timestamp: upEvent.timestamp,
+    durationMs: upEvent.timestamp - downAt,
+    timestamps: Object.freeze([downAt, upEvent.timestamp]),
+    ...(keyIndex !== undefined ? { keyIndex } : {}),
+  })
+
+const dblTap = (
+  upEvent: GestureEvent,
+  firstDownAt: number,
+  firstUpAt: number,
+  secondDownAt: number,
+  keyIndex?: number,
+): GestureResult =>
+  Object.freeze({
+    kind: "dbl-tap",
+    timestamp: upEvent.timestamp,
+    durationMs: upEvent.timestamp - firstDownAt,
+    timestamps: Object.freeze([
+      firstDownAt,
+      firstUpAt,
+      secondDownAt,
+      upEvent.timestamp,
+    ]),
+    ...(keyIndex !== undefined ? { keyIndex } : {}),
+  })
+
+const hold = (
+  timestamp: number,
+  downAt: number,
+  keyIndex?: number,
+): GestureResult =>
+  Object.freeze({
+    kind: "hold",
+    timestamp,
+    durationMs: timestamp - downAt,
+    timestamps: Object.freeze([downAt, timestamp]),
+    ...(keyIndex !== undefined ? { keyIndex } : {}),
+  })
+
+const clearTimer = (timer: ReturnType<typeof setTimeout> | undefined): void => {
+  if (timer !== undefined) clearTimeout(timer)
+}
+
+export interface GestureDetectorOptions {
+  readonly onGesture?: (result: GestureResult) => void
+}
+
+export interface GestureDetector {
+  detect(event: GestureEvent): GestureResult | null
+  reset(): void
+}
+
+const createKeyState = (keyIndex: number | undefined): KeyState => ({
+  name: "idle",
+  keyIndex,
+})
+
+export const createGestureDetector = (
+  options: GestureDetectorOptions = {},
+): GestureDetector => {
+  const states = new Map<number, KeyState>()
+  const { onGesture } = options
+
+  const getOrCreateState = (keyIndex: number | undefined): KeyState => {
+    const k = keyIndex ?? -1
+    const existing = states.get(k)
+    if (existing !== undefined) return existing
+    const s = createKeyState(keyIndex)
+    if (keyIndex !== undefined) states.set(k, s)
+    return s
+  }
+
+  const setState = (keyIndex: number | undefined, next: KeyState): void => {
+    const k = keyIndex ?? -1
+    if (k !== undefined) states.set(k, next)
+  }
+
+  const detect = (event: GestureEvent): GestureResult | null => {
+    const key = event.keyIndex
+    const state = getOrCreateState(key)
+    const k = key ?? -1
+
+    switch (state.name) {
+      case "idle":
+        if (event.type === "down") {
+          for (const [otherK, otherState] of states) {
+            if (otherState.name === "waiting-second") {
+              clearTimer(otherState.timer)
+              states.set(otherK, {
+                name: "idle",
+                keyIndex: otherState.keyIndex,
+              })
+            }
+          }
+          const downAt = event.timestamp
+          const newState: KeyState = {
+            name: "holding",
+            downAt,
+            timer: setTimeout(() => {
+              const s = states.get(k)
+              if (s?.name === "holding") {
+                s.emittedHold = true
+                onGesture?.(hold(downAt + HOLD_ACTION_DELAY_MS, downAt, key))
+              }
+            }, HOLD_ACTION_DELAY_MS),
+            keyIndex: key,
+          }
+          setState(key, newState)
+          return null
+        }
+        break
+
+      case "holding": {
+        if (event.type === "up") {
+          const duration = event.timestamp - state.downAt
+          clearTimer(state.timer)
+          if (duration >= HOLD_ACTION_DELAY_MS) {
+            setState(key, { name: "idle", keyIndex: key })
+            return hold(event.timestamp, state.downAt, key)
+          }
+          const newState: KeyState = {
+            name: "waiting-second",
+            firstUpAt: event.timestamp,
+            firstDownAt: state.downAt,
+            timer: setTimeout(() => {
+              const s = states.get(k)
+              if (s?.name === "waiting-second") {
+                onGesture?.(
+                  tap(
+                    { type: "up", timestamp: s.firstUpAt, keyIndex: key },
+                    s.firstDownAt,
+                    key,
+                  ),
+                )
+                states.delete(k)
+              }
+            }, DOUBLE_TAP_DELAY_MS),
+            keyIndex: key,
+          }
+          setState(key, newState)
+          return null
+        }
+        break
+      }
+
+      case "waiting-second": {
+        clearTimer(state.timer)
+        if (event.type === "down") {
+          if (event.keyIndex !== key) {
+            const t = tap(
+              { type: "up", timestamp: state.firstUpAt, keyIndex: key },
+              state.firstDownAt,
+              key,
+            )
+            onGesture?.(t)
+            setState(key, { name: "idle", keyIndex: key })
+            return null
+          }
+          const newState: KeyState = {
+            name: "second-down",
+            firstUpAt: state.firstUpAt,
+            firstDownAt: state.firstDownAt,
+            secondDownAt: event.timestamp,
+            keyIndex: key,
+          }
+          setState(key, newState)
+          return null
+        }
+        if (event.type === "up") {
+          const t = tap(event, state.firstDownAt, key)
+          setState(key, { name: "idle", keyIndex: key })
+          return t
+        }
+        break
+      }
+
+      case "second-down":
+        if (event.type === "up") {
+          const d = dblTap(
+            event,
+            state.firstDownAt,
+            state.firstUpAt,
+            state.secondDownAt,
+            key,
+          )
+          setState(key, { name: "idle", keyIndex: key })
+          onGesture?.(d)
+          return d
+        }
+        break
+    }
+
+    return null
+  }
+
+  const reset = (): void => {
+    for (const s of states.values()) {
+      if (s.name === "holding") clearTimer(s.timer)
+      if (s.name === "waiting-second") clearTimer(s.timer)
+    }
+    states.clear()
+  }
+
+  return Object.freeze({ detect, reset })
+}
+
+export const nextGesture = (
+  events: ReadonlyArray<GestureEvent>,
+): GestureResult | null => {
+  let state: KeyState = { name: "idle" }
+
+  for (const event of events) {
+    switch (state.name) {
+      case "idle":
+        if (event.type === "down") {
+          state = {
+            name: "holding",
+            downAt: event.timestamp,
+            timer: undefined,
+            keyIndex: event.keyIndex,
+          }
+        }
+        break
+
+      case "holding":
+        if (event.type === "up") {
+          const duration = event.timestamp - state.downAt
+          if (duration >= HOLD_ACTION_DELAY_MS) {
+            return hold(event.timestamp, state.downAt, state.keyIndex)
+          }
+          state = {
+            name: "waiting-second",
+            firstUpAt: event.timestamp,
+            firstDownAt: state.downAt,
+            timer: undefined,
+            keyIndex: state.keyIndex,
+          }
+        }
+        break
+
+      case "waiting-second":
+        if (event.type === "down") {
+          if (event.keyIndex !== state.keyIndex) {
+            return tap(
+              {
+                type: "up",
+                timestamp: state.firstUpAt,
+                keyIndex: state.keyIndex,
+              },
+              state.firstDownAt,
+              state.keyIndex,
+            )
+          }
+          state = {
+            name: "second-down",
+            firstUpAt: state.firstUpAt,
+            firstDownAt: state.firstDownAt,
+            secondDownAt: event.timestamp,
+            keyIndex: state.keyIndex,
+          }
+        } else if (event.type === "up") {
+          return tap(event, state.firstDownAt, state.keyIndex)
+        }
+        break
+
+      case "second-down":
+        if (event.type === "up") {
+          return dblTap(
+            event,
+            state.firstDownAt,
+            state.firstUpAt,
+            state.secondDownAt,
+            state.keyIndex,
+          )
+        }
+        break
+    }
+  }
+
+  if (state.name === "waiting-second") {
+    return tap(
+      { type: "up", timestamp: state.firstUpAt, keyIndex: state.keyIndex },
+      state.firstDownAt,
+      state.keyIndex,
+    )
+  }
+
+  return null
+}

package/src/core/icon-asset-registry.ts

@@ -0,0 +1,127 @@
+import { readFileSync, statSync } from "node:fs"
+
+import { makeAssetId } from "./asset-id"
+import { inferMimeFromPath } from "./mime"
+import { resolveIconSource } from "../render/icon-source-resolver"
+import type { ResolveIconPathOptions } from "../render/icon-source-resolver"
+import type { RuntimeButton, RuntimeDeck } from "@/deck"
+import type pino from "pino"
+
+export const MAX_ASSET_SIZE = 200 * 1024
+
+export interface Asset {
+  readonly id: string
+  readonly fullPath: string
+  readonly mime: string
+  readonly src: string
+  readonly filesize: number
+  readonly mtime: number
+}
+
+const assets = new Map<string, Asset>()
+
+export const clearAssets = (): void => {
+  assets.clear()
+}
+
+const registerOneIcon = (
+  icon: string,
+  resolverOptions: ResolveIconPathOptions,
+  logger?: pino.Logger,
+): void => {
+  let resolved
+  try {
+    resolved = resolveIconSource(icon, resolverOptions)
+  } catch (err) {
+    logger?.warn(
+      { icon, err: (err as Error).message },
+      "skipping unresolvable icon",
+    )
+    return
+  }
+  if (resolved.kind !== "asset") return
+  if (assets.has(resolved.fullPath)) return
+
+  let stats
+  try {
+    stats = statSync(resolved.fullPath)
+  } catch (err) {
+    logger?.warn(
+      {
+        icon,
+        fullPath: resolved.fullPath,
+        err: (err as Error).message,
+      },
+      `icon file missing or unreadable: '${icon}' resolved to '${resolved.fullPath}' — ${(err as Error).message}`,
+    )
+    return
+  }
+  const filesize = stats.size
+  if (filesize > MAX_ASSET_SIZE) {
+    logger?.warn(
+      { fullPath: resolved.fullPath, filesize, limit: MAX_ASSET_SIZE },
+      "icon exceeds MAX_ASSET_SIZE; skipping",
+    )
+    return
+  }
+  let raw: Buffer
+  try {
+    raw = readFileSync(resolved.fullPath)
+  } catch (err) {
+    logger?.warn(
+      { fullPath: resolved.fullPath, err: (err as Error).message },
+      "icon read failed",
+    )
+    return
+  }
+  const mime = inferMimeFromPath(resolved.fullPath)
+  const id = makeAssetId(resolved.fullPath, filesize, stats.mtimeMs)
+  assets.set(resolved.fullPath, {
+    id,
+    fullPath: resolved.fullPath,
+    mime,
+    src: `data:${mime};base64,${raw.toString("base64")}`,
+    filesize,
+    mtime: stats.mtimeMs,
+  })
+}
+
+const readButtonIcon = (button: RuntimeButton): string | undefined => {
+  const cfg = button.config
+  if (typeof cfg !== "object" || cfg === null) return undefined
+  const icon = (cfg as Record<string, unknown>).icon
+  return typeof icon === "string" && icon !== "" ? icon : undefined
+}
+
+export const registerIconForDeck = (
+  buttons: ReadonlyArray<RuntimeButton>,
+  resolverOptions: ResolveIconPathOptions,
+  logger?: pino.Logger,
+): void => {
+  for (const button of buttons) {
+    const icon = readButtonIcon(button)
+    if (icon !== undefined) registerOneIcon(icon, resolverOptions, logger)
+  }
+}
+
+export const registerDeckIcon = (
+  deck: Pick<RuntimeDeck, "icon">,
+  resolverOptions: ResolveIconPathOptions,
+  logger?: pino.Logger,
+): void => {
+  if (typeof deck.icon !== "string" || deck.icon === "") return
+  registerOneIcon(deck.icon, resolverOptions, logger)
+}
+
+export const getUnsentAssets = (
+  sentIds: ReadonlySet<string>,
+): ReadonlyArray<Asset> => {
+  const out: Asset[] = []
+  for (const asset of assets.values()) {
+    if (!sentIds.has(asset.id)) out.push(asset)
+  }
+  return out
+}
+
+export const getAssetByPath = (fullPath: string): Asset | undefined =>
+  assets.get(fullPath)

package/src/core/icon-source.ts

@@ -0,0 +1,86 @@
+// Single-emoji source matcher. Accepts:
+//   - one extended-pictographic char (with optional VS16 after each
+//     segment; ZWJ chains extend it — covers 🏳️‍🌈, 🧑‍🦽, 👨‍👩‍👧, etc.),
+//   - OR two regional-indicator chars (a country flag like 🇪🇸).
+// Two regional indicators don't have `Emoji_Presentation` individually
+// (the flag is only "complete" as a pair), so the old single-codepoint
+// regex rejected every country flag.
+export const EMOJI_RE =
+  /^(?:[\p{Extended_Pictographic}\p{Emoji_Component}]\uFE0F?(?:\u200D[\p{Extended_Pictographic}\p{Emoji_Component}]\uFE0F?)*|\p{Regional_Indicator}{2})$/u
+
+export const ICON_FALLBACK = "icon://alert-circle"
+
+// Runtime-safe absolute path detection (POSIX: leading '/'; Windows:
+// leading '\' or drive letter like 'C:\' or 'C:/'). Implemented as a
+// regex so this module is safe to import from both the Node runtime and
+// the browser bundle (which can't use `node:path.isAbsolute`).
+const ABSOLUTE_PATH_RE = /^(?:\/|\\|[A-Za-z]:[\\/])/
+
+/**
+ * Validate that a runtime icon source is one of:
+ *   - `icon://<name>`   — Lucide icon by name (resolved by the runtime
+ *                         `resolveIconSource`)
+ *   - `asset://<id>`    — pre-resolved asset id from the registry
+ *   - `addon://<a>/<p>` — asset inside an addon's frontendEntry dir
+ *   - `builtin://<p>`   — asset inside the builtin addon's dir
+ *   - absolute path     — asset resolved directly
+ *   - relative path     — asset resolved against the config's baseDirs
+ *                         (e.g. `./assets/chrome.svg`, `../shared/icon.svg`,
+ *                         `~/Pictures/x.png`)
+ *   - a single emoji (Presentation, or base+VS16 like ✈️; also
+ *     regional-indicator pair flags like 🇪🇸, and ZWJ sequences
+ *     like 🏳️‍🌈 or 👨‍👩‍👧)
+ *
+ * Rejected: empty string, "%", "abc", multi-char (e.g. "abc🔥"),
+ * inline URLs (data:, http://, https://, file://) — these must be
+ * pre-resolved to asset:// before reaching the runtime.
+ *
+ * Anything rejected here triggers a runtime fallback (alert-circle
+ * Lucide icon) AND, at config-load, a zod validation error.
+ */
+export const isIconSource = (s: unknown): s is string => {
+  if (typeof s !== "string" || s.length === 0) return false
+  if (EMOJI_RE.test(s)) return true
+  if (s.startsWith("icon://") && s.length > "icon://".length) return true
+  if (s.startsWith("asset://") && s.length > "asset://".length) return true
+  if (s.startsWith("addon://")) {
+    // addon://<addonName>/<subPath> — must have both segments
+    const rest = s.slice("addon://".length)
+    const slash = rest.indexOf("/")
+    if (slash > 0 && slash < rest.length - 1) return true
+    return false
+  }
+  if (s.startsWith("builtin://") && s.length > "builtin://".length) return true
+  // Inline URLs are explicitly rejected by the runtime resolver.
+  if (
+    s.startsWith("data:") ||
+    s.startsWith("http://") ||
+    s.startsWith("https://") ||
+    s.startsWith("file://")
+  ) {
+    return false
+  }
+  // Absolute path (POSIX '/' or Windows '\' or 'C:\').
+  if (ABSOLUTE_PATH_RE.test(s)) return true
+  // Reject anything that looks like a scheme-prefixed URL the runtime
+  // doesn't understand (e.g. "abc://x"). The runtime would treat it as a
+  // path and produce a garbage absolute path. Recognized schemes
+  // (icon://, asset://, addon://, builtin://) are handled above.
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(s)) return false
+  // Relative paths: must contain a path separator OR start with one of
+  // the recognized path prefixes ("./", "../", "~/", "~\\"). Single-char
+  // paths like "." are also valid.
+  if (
+    s === "." ||
+    s === "~" ||
+    s.startsWith("./") ||
+    s.startsWith("../") ||
+    s.startsWith("~/") ||
+    s.startsWith("~\\") ||
+    /[\\/]/.test(s) ||
+    s.startsWith("/")
+  ) {
+    return true
+  }
+  return false
+}

package/src/core/index.ts

@@ -0,0 +1,30 @@
+export {
+  createPubSub,
+  type CreatePubSubOptions,
+  type FlushCallback,
+  type Payload,
+  type PubSub,
+  type Unsubscribe,
+} from "./pub-sub"
+
+export {
+  DOUBLE_TAP_DELAY_MS,
+  HOLD_ACTION_DELAY_MS,
+  type GestureEvent,
+  type GestureKind,
+  type GestureResult,
+  type GestureType,
+  nextGesture,
+} from "./gesture-state"
+
+export { createStore, type Scope, type ScopeKind, type Store } from "./store"
+
+export {
+  NEXT_PAGE_MARKER,
+  type NextPageMarker,
+  type Page,
+  type PaginateOptions,
+  type PaginatedItem,
+  type PaginationResult,
+  paginate,
+} from "./pagination"

package/src/core/mime.ts

@@ -0,0 +1,16 @@
+const EXT_TO_MIME: Readonly<Record<string, string>> = {
+  svg: "image/svg+xml",
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  webp: "image/webp",
+  gif: "image/gif",
+  ico: "image/x-icon",
+}
+
+export const inferMimeFromPath = (path: string): string => {
+  const dot = path.lastIndexOf(".")
+  if (dot === -1 || dot === path.length - 1) return "application/octet-stream"
+  const ext = path.slice(dot + 1).toLowerCase()
+  return EXT_TO_MIME[ext] ?? "application/octet-stream"
+}

package/src/core/pagination.ts

@@ -0,0 +1,90 @@
+export const NEXT_PAGE_MARKER = "__nextPageMarker" as const
+
+export type NextPageMarker = typeof NEXT_PAGE_MARKER
+
+export interface PaginatedItem<T> {
+  readonly id: string
+  readonly value: T
+}
+
+export interface Page<T> {
+  readonly items: ReadonlyArray<PaginatedItem<T> | null>
+  readonly pageIndex: number
+  readonly totalPages: number
+  readonly hasNext: boolean
+  readonly hasPrev: boolean
+}
+
+export interface PaginationResult<T> {
+  readonly pages: ReadonlyArray<Page<T>>
+  readonly totalItems: number
+}
+
+export interface PaginateOptions {
+  readonly keyCount: number
+  readonly pageSize?: number
+}
+
+export const paginationReservedPositions = (
+  keyCount: number,
+  paginated: boolean,
+): number[] => (paginated && keyCount > 1 ? [keyCount - 2] : [])
+
+const buildPageItem = <T>(id: string, value: T): PaginatedItem<T> => ({
+  id,
+  value,
+})
+
+export const paginate = <T>(
+  items: ReadonlyArray<T>,
+  opts: PaginateOptions,
+): PaginationResult<T> => {
+  if (opts.keyCount <= 0) {
+    throw new Error("paginate: keyCount must be > 0")
+  }
+  const pageSize = opts.pageSize ?? opts.keyCount - 2
+  if (pageSize <= 0) {
+    throw new Error("paginate: pageSize must be > 0")
+  }
+
+  const totalItems = items.length
+  const totalPages = totalItems === 0 ? 0 : Math.ceil(totalItems / pageSize)
+  if (totalPages === 0) {
+    return { pages: [], totalItems: 0 }
+  }
+
+  const pages: Array<Page<T>> = []
+  for (let pageIndex = 0; pageIndex < totalPages; pageIndex++) {
+    const start = pageIndex * pageSize
+    const end = Math.min(start + pageSize, totalItems)
+    const slice = items.slice(start, end)
+
+    const pageItems: Array<PaginatedItem<T> | null> = slice.map((value, i) =>
+      buildPageItem(`${pageIndex}-${i}`, value),
+    )
+
+    const hasMultiplePages = totalPages > 1
+    if (hasMultiplePages) {
+      const isFullPage = pageItems.length >= pageSize
+      const markerIndex = isFullPage ? pageSize - 1 : pageItems.length
+      pageItems.splice(markerIndex, 0, {
+        id: NEXT_PAGE_MARKER,
+        value: NEXT_PAGE_MARKER,
+      } as PaginatedItem<T>)
+    }
+
+    while (pageItems.length < pageSize) {
+      pageItems.push(null)
+    }
+
+    pages.push({
+      items: pageItems,
+      pageIndex,
+      totalPages,
+      hasNext: pageIndex < totalPages - 1,
+      hasPrev: pageIndex > 0,
+    })
+  }
+
+  return { pages, totalItems }
+}