ink-framework-overlays 0.0.0-stage → 0.1.0-alpha.13

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vandam Dinh
+
+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/ink-native.json

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "modules": { "*": ["overlays"] }
+}

package/package.json

@@ -1,6 +1,24 @@
 {
   "name": "ink-framework-overlays",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-alpha.13",
+  "exports": {
+    ".": "./src/index.ts",
+    "./runtime": "./src/runtime.tsx"
+  },
+  "peerDependencies": {
+    "ink": "npm:ink-framework@0.1.0-alpha.13",
+    "react": "19.2.8"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/No-Scrolling/ink.git",
+    "directory": "packages/overlays"
+  },
+  "files": [
+    "src",
+    "*.json",
+    "*.ts",
+    "*.md"
+  ]
+}

package/src/index.ts

@@ -0,0 +1,70 @@
+import { createElement, type ComponentType } from "ink/internal/react";
+import type { Snapshot, SnapshotSource } from "ink";
+import { callNative, onNativeMessage } from "ink/native";
+import { overlayComponents } from "./internal";
+
+export type OverlayPosition = "top" | "center" | "bottom";
+export type OverlayOptions = { width?: number; height: number; position?: OverlayPosition; offset?: number };
+export type OverlayState = Readonly<{ visible: boolean; id: string | null }>;
+
+let snapshot: Snapshot<OverlayState> = { status: "loading" };
+const listeners = new Set<() => void>();
+function publish(data: OverlayState) {
+  snapshot = { status: "ready", data: Object.freeze(data) };
+  for (const listener of listeners) listener();
+}
+function decode(value: unknown): OverlayState {
+  if (!value || typeof value !== "object" || !("visible" in value) || typeof value.visible !== "boolean"
+    || !("id" in value) || (value.id !== null && typeof value.id !== "string")) throw new Error("Invalid overlay state");
+  return { visible: value.visible, id: value.id };
+}
+onNativeMessage("overlays-changed", message => { publish(decode(message.data)); });
+async function read(operation: string): Promise<OverlayState> {
+  try {
+    const data = decode(JSON.parse(await callNative("overlays", operation, {})));
+    publish(data);
+    return data;
+  } catch (error) {
+    snapshot = { status: "error", error: error instanceof Error ? error : new Error(String(error)) };
+    for (const listener of listeners) listener();
+    throw error;
+  }
+}
+
+export function defineOverlay<Props extends object>(definition: { id: string; component: ComponentType<Props> }) {
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(definition.id)) throw new TypeError("Invalid overlay ID");
+  if (overlayComponents.has(definition.id)) throw new Error(`Duplicate overlay: ${definition.id}`);
+  overlayComponents.set(definition.id, props => createElement(definition.component, props as Props));
+  return {
+    async show(props: Props, options: OverlayOptions): Promise<void> {
+      await callNative("overlays", "show", { id: definition.id, props, options });
+    },
+    async update(props: Props, options?: OverlayOptions): Promise<void> {
+      await callNative("overlays", "update", { id: definition.id, props, options });
+    },
+    async hide(): Promise<void> {
+      await callNative("overlays", "hide", { id: definition.id });
+    },
+  };
+}
+
+export const overlays: SnapshotSource<OverlayState> & {
+  isAllowed(): Promise<boolean>;
+  requestPermission(): Promise<void>;
+  getState(): Promise<OverlayState>;
+} = {
+  isAllowed: async () => (await callNative("overlays", "permission", {})) === "true",
+  async requestPermission(): Promise<void> {
+    await callNative("overlays", "request-permission", {}, { timeoutMs: 900_000 });
+  },
+  getState: () => read("state"),
+  getSnapshot: () => snapshot,
+  subscribe(listener) {
+    listeners.add(listener);
+    if (listeners.size === 1) void read("watch").catch(() => {});
+    return () => {
+      listeners.delete(listener);
+      if (listeners.size === 0) void callNative("overlays", "unwatch", {}).catch(() => {});
+    };
+  },
+};

package/src/internal.ts

@@ -0,0 +1,21 @@
+import type { ReactNode } from "ink/internal/react";
+import { onNativeMessage } from "ink/native";
+
+export const overlayComponents = new Map<string, (props: object) => ReactNode>();
+let content: { id: string; props: object } | null = null;
+const listeners = new Set<() => void>();
+onNativeMessage("overlay-content", message => {
+  if (typeof message.id !== "string" || typeof message.props !== "object" || message.props === null || Array.isArray(message.props)) {
+    throw new TypeError("Invalid overlay content");
+  }
+  content = { id: message.id, props: message.props };
+  for (const listener of listeners) listener();
+});
+
+export const overlayContent = {
+  getSnapshot: () => content,
+  subscribe(listener: () => void) {
+    listeners.add(listener);
+    return () => { listeners.delete(listener); };
+  },
+};

package/src/runtime.tsx

@@ -0,0 +1,15 @@
+import { createElement, useSyncExternalStore } from "ink/internal/react";
+import { render } from "ink/renderer";
+import { overlayComponents, overlayContent } from "./internal";
+
+function OverlayRoot() {
+  const content = useSyncExternalStore(overlayContent.subscribe, overlayContent.getSnapshot);
+  if (!content) return null;
+  const component = overlayComponents.get(content.id);
+  if (!component) throw new Error(`Overlay is not registered in the overlay entry point: ${content.id}`);
+  return createElement(component, { ...content.props, key: content.id });
+}
+
+export function startOverlays() {
+  render(<OverlayRoot />);
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.