@adukiorg/anza 0.2.0

package/types/core/ui/index.d.ts

@@ -0,0 +1,446 @@
+/**
+ * types/core/ui/index.d.ts
+ *
+ * Strict TypeScript declarations for the Native UI runtime.
+ */
+
+export type TaskPriority = 'user-blocking' | 'user-visible' | 'background';
+
+export type MaybePromise<T> = T | Promise<T>;
+
+export type Disposer = () => void;
+
+export type RefsMap = Record<string, Element>;
+
+export type ElementRefs<T> = {
+  [K in keyof T]: Element;
+};
+
+export type PropConstructor =
+  | BooleanConstructor
+  | NumberConstructor
+  | StringConstructor;
+
+export type PropValueFromConstructor<T> =
+  T extends BooleanConstructor ? boolean :
+  T extends NumberConstructor ? number :
+  T extends StringConstructor ? string :
+  never;
+
+export interface PropConfig<T extends PropConstructor = PropConstructor> {
+  type: T;
+  default?: PropValueFromConstructor<T>;
+  state?: boolean;
+  reflect?: boolean;
+}
+
+export type AnyPropConfig =
+  | PropConfig<BooleanConstructor>
+  | PropConfig<NumberConstructor>
+  | PropConfig<StringConstructor>;
+
+export type PropsDefinition = Record<string, AnyPropConfig>;
+
+export type InferProps<Props extends PropsDefinition> = {
+  [K in keyof Props]: PropValueFromConstructor<Props[K]['type']>;
+};
+
+export type ComponentHost<
+  Props extends PropsDefinition = {},
+  Methods extends Record<string, (...args: any[]) => any> = {}
+> = HTMLElement & InferProps<Props> & Methods;
+
+export type InternalsFor<Form extends boolean> =
+  Form extends true ? ElementInternals : ElementInternals | undefined;
+
+export interface TagsApi {
+  one<E extends Element = Element>(selector: string): E | null;
+  all<E extends Element = Element>(selector: string): E[];
+  each<E extends Element = Element>(
+    selector: string,
+    fn: (element: E, index: number) => void
+  ): void;
+  has(selector: string): boolean;
+  clear(): void;
+}
+
+export interface DelegatedEventOptions extends AddEventListenerOptions {
+  signal?: AbortSignal;
+  once?: boolean;
+}
+
+export type DelegatedEventHandler<
+  EventType extends Event = Event,
+  Target extends Element = Element
+> = (event: EventType, target: Target) => void;
+
+export interface DelegatedEventBinder<EventType extends Event = Event> {
+  <Target extends Element = Element>(
+    selector: string,
+    handler: DelegatedEventHandler<EventType, Target>,
+    options?: AbortSignal | DelegatedEventOptions
+  ): Disposer;
+
+  once<Target extends Element = Element>(
+    selector: string,
+    handler: DelegatedEventHandler<EventType, Target>,
+    options?: AbortSignal | Omit<DelegatedEventOptions, 'once'>
+  ): Disposer;
+}
+
+export type EventDelegator = {
+  [K in keyof GlobalEventHandlersEventMap]: DelegatedEventBinder<GlobalEventHandlersEventMap[K]>;
+} & {
+  [customEvent: string]: DelegatedEventBinder<Event>;
+};
+
+export interface WatchOptions {
+  signal?: AbortSignal;
+  once?: boolean;
+}
+
+export type WatchTarget<T extends Element = Element> = string | T;
+
+export type AttrWatchHandler<T extends Element = Element> = (
+  attrName: string,
+  newValue: string | null,
+  oldValue: string | null,
+  element: T
+) => void;
+
+export type KidsWatchHandler<T extends Element = Element> = (
+  change: {
+    added: Node[];
+    removed: Node[];
+  },
+  element: T
+) => void;
+
+export type TextWatchHandler<T extends Element = Element> = (
+  newText: string,
+  oldText: string | null,
+  element: T | null
+) => void;
+
+export type TreeWatchHandler<T extends Element = Element> = (
+  records: MutationRecord[],
+  element: T | null
+) => void;
+
+export interface WatchApi {
+  attr: {
+    <T extends Element = Element>(
+      target: WatchTarget<T>,
+      attr: string | readonly string[] | '*',
+      handler: AttrWatchHandler<T>,
+      options?: AbortSignal | WatchOptions
+    ): Disposer;
+
+    once<T extends Element = Element>(
+      target: WatchTarget<T>,
+      attr: string | readonly string[] | '*',
+      handler: AttrWatchHandler<T>,
+      options?: AbortSignal | Omit<WatchOptions, 'once'>
+    ): Disposer;
+  };
+
+  kids: {
+    <T extends Element = Element>(
+      target: WatchTarget<T>,
+      handler: KidsWatchHandler<T>,
+      options?: AbortSignal | WatchOptions
+    ): Disposer;
+
+    <T extends Element = Element>(
+      target: WatchTarget<T>,
+      config: { deep?: boolean },
+      handler: KidsWatchHandler<T>,
+      options?: AbortSignal | WatchOptions
+    ): Disposer;
+
+    once<T extends Element = Element>(
+      target: WatchTarget<T>,
+      handler: KidsWatchHandler<T>,
+      options?: AbortSignal | Omit<WatchOptions, 'once'>
+    ): Disposer;
+
+    once<T extends Element = Element>(
+      target: WatchTarget<T>,
+      config: { deep?: boolean },
+      handler: KidsWatchHandler<T>,
+      options?: AbortSignal | Omit<WatchOptions, 'once'>
+    ): Disposer;
+  };
+
+  text: {
+    <T extends Element = Element>(
+      target: WatchTarget<T>,
+      handler: TextWatchHandler<T>,
+      options?: AbortSignal | WatchOptions
+    ): Disposer;
+
+    once<T extends Element = Element>(
+      target: WatchTarget<T>,
+      handler: TextWatchHandler<T>,
+      options?: AbortSignal | Omit<WatchOptions, 'once'>
+    ): Disposer;
+  };
+
+  tree: {
+    <T extends Element = Element>(
+      target: WatchTarget<T>,
+      handler: TreeWatchHandler<T>,
+      options?: AbortSignal | WatchOptions
+    ): Disposer;
+
+    once<T extends Element = Element>(
+      target: WatchTarget<T>,
+      handler: TreeWatchHandler<T>,
+      options?: AbortSignal | Omit<WatchOptions, 'once'>
+    ): Disposer;
+  };
+}
+
+export interface BaseLifecycleContext<
+  Props extends PropsDefinition = {},
+  Refs extends ElementRefs<Refs> = RefsMap,
+  Form extends boolean = false,
+  Methods extends Record<string, (...args: any[]) => any> = {}
+> {
+  el: ComponentHost<Props, Methods>;
+  ctrl: AbortController;
+  tags: TagsApi;
+  on: EventDelegator;
+  refs: Readonly<Refs>;
+  watch: WatchApi;
+  internals: InternalsFor<Form>;
+}
+
+export type MountContext<
+  Props extends PropsDefinition = {},
+  Refs extends ElementRefs<Refs> = RefsMap,
+  Form extends boolean = false,
+  Methods extends Record<string, (...args: any[]) => any> = {}
+> = BaseLifecycleContext<Props, Refs, Form, Methods>;
+
+export type UpdateContext<
+  Props extends PropsDefinition = {},
+  Refs extends ElementRefs<Refs> = RefsMap,
+  Form extends boolean = false,
+  Methods extends Record<string, (...args: any[]) => any> = {}
+> = keyof Props extends never
+  ? never
+  : {
+      [K in keyof Props & string]:
+        BaseLifecycleContext<Props, Refs, Form, Methods> & {
+          name: K;
+          val: PropValueFromConstructor<Props[K]['type']>;
+          prev: PropValueFromConstructor<Props[K]['type']>;
+          old: PropValueFromConstructor<Props[K]['type']>;
+        }
+    }[keyof Props & string];
+
+export type UnmountContext<
+  Props extends PropsDefinition = {},
+  Refs extends ElementRefs<Refs> = RefsMap,
+  Form extends boolean = false,
+  Methods extends Record<string, (...args: any[]) => any> = {}
+> = Pick<
+  BaseLifecycleContext<Props, Refs, Form, Methods>,
+  'el' | 'tags' | 'refs' | 'watch' | 'internals'
+>;
+
+export interface ElementSpec<
+  Props extends PropsDefinition = {},
+  Refs extends ElementRefs<Refs> = RefsMap,
+  Form extends boolean = false,
+  Methods extends Record<string, (...args: any[]) => any> = {}
+> {
+  template?: string;
+  style?: string;
+  mode?: ShadowRootMode;
+  props?: Props;
+  form?: Form;
+  url?: string;
+  container?: string;
+  query?: readonly string[] | string[];
+  meta?: Record<string, unknown>;
+
+  mount?: (
+    context: MountContext<Props, Refs, Form, Methods>
+  ) => MaybePromise<void>;
+
+  update?: (
+    context: UpdateContext<Props, Refs, Form, Methods>
+  ) => MaybePromise<void>;
+
+  unmount?: (
+    context: UnmountContext<Props, Refs, Form, Methods>
+  ) => void;
+
+  associated?: (
+    this: ComponentHost<Props, Methods>,
+    form: HTMLFormElement | null
+  ) => void;
+
+  disabled?: (
+    this: ComponentHost<Props, Methods>,
+    value: boolean
+  ) => void;
+
+  reset?: (
+    this: ComponentHost<Props, Methods>
+  ) => void;
+
+  restore?: (
+    this: ComponentHost<Props, Methods>,
+    state: unknown,
+    mode: string
+  ) => void;
+
+  methods?: Methods;
+}
+
+export interface SwapViewOptions {
+  direction?: 'push' | 'pop' | 'replace' | string;
+  params?: Record<string, string>;
+}
+
+export type ContainerHost<Props extends PropsDefinition = {}> =
+  ComponentHost<Props> & {
+    swapView(newElement: Element, options?: SwapViewOptions): Promise<void>;
+  };
+
+export type ContainerMountContext<
+  Props extends PropsDefinition = {},
+  Refs extends ElementRefs<Refs> = RefsMap
+> = Omit<MountContext<Props, Refs, false>, 'el'> & {
+  el: ContainerHost<Props>;
+};
+
+export interface ContainerSpec<
+  Props extends PropsDefinition = {},
+  Refs extends ElementRefs<Refs> = RefsMap
+> extends Omit<
+  ElementSpec<Props, Refs, false>,
+  'mount' | 'update' | 'unmount' | 'form'
+> {
+  mount?: (
+    context: ContainerMountContext<Props, Refs>
+  ) => MaybePromise<void>;
+
+  update?: (
+    context: UpdateContext<Props, Refs, false>
+  ) => MaybePromise<void>;
+
+  unmount?: (
+    context: UnmountContext<Props, Refs, false>
+  ) => void;
+}
+
+export interface ObserveApi {
+  resize(
+    el: Element,
+    fn: (entries: ResizeObserverEntry[]) => void,
+    signal?: AbortSignal
+  ): Disposer;
+
+  intersection(
+    el: Element,
+    fn: (entries: IntersectionObserverEntry[]) => void,
+    signal?: AbortSignal,
+    options?: IntersectionObserverInit
+  ): Disposer;
+
+  mutation(
+    el: Node,
+    fn: (mutations: MutationRecord[]) => void,
+    signal?: AbortSignal,
+    options?: MutationObserverInit
+  ): Disposer;
+
+  performance(
+    types: string[],
+    fn: (list: PerformanceObserverEntryList) => void,
+    signal?: AbortSignal,
+    options?: PerformanceObserverInit
+  ): Disposer;
+}
+
+export interface ViewTransitionLike<T = unknown> {
+  finished: Promise<T>;
+  updateCallbackDone: Promise<T>;
+  ready: Promise<unknown>;
+  skipTransition(): void;
+}
+
+export class BaseElement extends HTMLElement {
+  ctrl: AbortController | null;
+
+  constructor();
+  connectedCallback(): void;
+  disconnectedCallback(): void;
+  mount(): void;
+  unmount(): void;
+}
+
+export function define<TagName extends string>(
+  tagName: TagName,
+  elementClass: CustomElementConstructor
+): void;
+
+export function element<
+  TagName extends string,
+  Props extends PropsDefinition = {},
+  Refs extends ElementRefs<Refs> = RefsMap,
+  Form extends boolean = false,
+  Methods extends Record<string, (...args: any[]) => any> = {}
+>(
+  tagName: TagName,
+  spec: ElementSpec<Props, Refs, Form, Methods>,
+  base?: string | URL
+): void;
+
+export function container<
+  TagName extends string,
+  Props extends PropsDefinition = {},
+  Refs extends ElementRefs<Refs> = RefsMap
+>(
+  tagName: TagName,
+  spec: ContainerSpec<Props, Refs>,
+  base?: string | URL
+): void;
+
+export function schedule<T>(
+  fn: () => T | Promise<T>,
+  priority?: TaskPriority
+): Promise<T>;
+
+export function scheduleFrame<T>(fn: () => T): Promise<T>;
+
+export function yieldTask(): Promise<void>;
+
+export function transition<T>(
+  fn: () => T
+): Promise<ViewTransitionLike<T>>;
+
+export function template(
+  strings: TemplateStringsArray,
+  ...values: unknown[]
+): DocumentFragment;
+
+export const observe: ObserveApi;
+
+export interface UiApi {
+  define: typeof define;
+  element: typeof element;
+  container: typeof container;
+  schedule: typeof schedule;
+  scheduleFrame: typeof scheduleFrame;
+  yield: typeof yieldTask;
+  transition: typeof transition;
+  template: typeof template;
+  observe: ObserveApi;
+}
+
+export const ui: UiApi;

package/types/core/workers/index.d.ts

@@ -0,0 +1,221 @@
+/**
+ * types/core/workers/index.d.ts
+ *
+ * TypeScript declarations for the multi-threaded concurrency layer.
+ * Source: plan.md Phase 1 — Contract
+ */
+
+// ---------------------------------------------------------------------------
+// Message contract
+// ---------------------------------------------------------------------------
+
+/** Shape of a message sent to a worker. */
+export interface WorkerRequest {
+  task: string;
+  payload?: any;
+  meta?: any;
+}
+
+/** Shape of a message received from a worker. */
+export interface WorkerResponse {
+  ok: boolean;
+  value?: any;
+  error?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Shared task options
+// ---------------------------------------------------------------------------
+
+export interface TaskOptions {
+  /** Data to clone-transfer to the worker. Must be structured-clone safe. */
+  payload?: any;
+  /** Scheduling priority. Default: 'user-visible'. */
+  priority?: 'user-blocking' | 'user-visible' | 'background';
+  /** Transferables handed off to the worker (sender loses access). */
+  transferables?: Transferable[];
+  /** Signal to cancel the in-flight or queued task. */
+  signal?: AbortSignal;
+  /** Milliseconds before the task is automatically aborted. */
+  timeout?: number;
+  /** Arbitrary metadata forwarded to the worker. */
+  meta?: any;
+  /** Pool size hint (used only when the pool is first created). */
+  size?: number;
+  /** Maximum pool size cap. */
+  max?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Dedicated worker
+// ---------------------------------------------------------------------------
+
+export interface RunOptions {
+  payload?: any;
+  transferables?: Transferable[];
+  signal?: AbortSignal;
+  timeout?: number;
+  meta?: any;
+}
+
+export declare class Dedicated {
+  constructor(script: string);
+  readonly closed: boolean;
+  run(task: string, options?: RunOptions): Promise<any>;
+  terminate(): void;
+}
+
+/** @deprecated Use Dedicated */
+export declare class DedicatedWorker extends Dedicated {}
+
+// ---------------------------------------------------------------------------
+// Worker pool
+// ---------------------------------------------------------------------------
+
+export interface PoolOptions {
+  size?: number;
+  max?: number;
+  idle?: number;
+}
+
+export interface PoolTaskOptions extends RunOptions {
+  priority?: 'user-blocking' | 'user-visible' | 'background';
+  idempotent?: boolean;
+}
+
+export declare class Pool {
+  constructor(script: string, opts?: PoolOptions);
+  readonly size: number;
+  readonly pending: number;
+  run(task: string, options?: PoolTaskOptions): Promise<any>;
+  terminate(): void;
+}
+
+/** @deprecated Use Pool */
+export declare class WorkerPool extends Pool {}
+
+// ---------------------------------------------------------------------------
+// Shared worker
+// ---------------------------------------------------------------------------
+
+export declare class Shared {
+  constructor(script: string, name?: string);
+  readonly connected: boolean;
+  readonly closed: boolean;
+  connect(): void;
+  send(message: any, transferables?: Transferable[]): void;
+  subscribe(fn: (msg: any) => void, signal?: AbortSignal): () => void;
+  close(): void;
+  /** @deprecated Use send() */
+  postMessage(msg: any, transfer?: Transferable[]): void;
+  /** @deprecated Use subscribe() */
+  onMessage(fn: (msg: any) => void, signal?: AbortSignal): () => void;
+}
+
+/** @deprecated Use Shared */
+export declare class SharedConnection extends Shared {}
+
+// ---------------------------------------------------------------------------
+// Locks
+// ---------------------------------------------------------------------------
+
+export interface LockOptions {
+  signal?: AbortSignal;
+  mode?: 'exclusive' | 'shared';
+  timeout?: number;
+  ifAvailable?: boolean;
+  steal?: boolean;
+}
+
+export declare function lock(
+  name: string,
+  fn: () => any | Promise<any>,
+  options?: LockOptions
+): Promise<any>;
+
+// ---------------------------------------------------------------------------
+// Broadcast
+// ---------------------------------------------------------------------------
+
+export interface BroadcastManager {
+  broadcast(name: string, payload: any): void;
+  subscribe(name: string, fn: (msg: any) => void, signal?: AbortSignal): () => void;
+  close(name: string): void;
+  clear(): void;
+}
+
+export declare const broadcast: BroadcastManager;
+
+// ---------------------------------------------------------------------------
+// Offscreen canvas
+// ---------------------------------------------------------------------------
+
+export interface OffscreenOptions {
+  onError?: (err: Error) => void;
+  onResize?: (dims: { width: number; height: number; dpr: number }) => void;
+}
+
+export interface ResizeOptions {
+  width?: number;
+  height?: number;
+  dpr?: number;
+}
+
+export declare class Offscreen {
+  constructor(canvas: HTMLCanvasElement, script: string, opts?: OffscreenOptions);
+  readonly ready: boolean;
+  readonly closed: boolean;
+  open(): Promise<this>;
+  send(payload: any, transferables?: Transferable[]): void;
+  resize(opts?: ResizeOptions): void;
+  close(): void;
+  /** @deprecated Use close() */
+  terminate(): void;
+}
+
+/** @deprecated Use Offscreen */
+export declare class OffscreenHandle extends Offscreen {}
+
+export declare function offscreen(
+  canvas: HTMLCanvasElement,
+  script: string,
+  opts?: OffscreenOptions
+): Promise<Offscreen>;
+
+// ---------------------------------------------------------------------------
+// Feature detection
+// ---------------------------------------------------------------------------
+
+export declare const has: {
+  worker: boolean;
+  shared: boolean;
+  channel: boolean;
+  locks: boolean;
+  offscreen: boolean;
+  isolated: boolean;
+};
+
+// ---------------------------------------------------------------------------
+// Facade
+// ---------------------------------------------------------------------------
+
+export declare const workers: {
+  /** Run a task in a lazily allocated pool. */
+  run(script: string, task: string, opts?: TaskOptions): Promise<any>;
+  /** Create a standalone dedicated worker (not pooled). */
+  dedicated(script: string): Dedicated;
+  /** Connect to a SharedWorker (or dedicated fallback). */
+  shared(script: string, name?: string): Shared;
+  /** Acquire a named lock and execute fn within it. */
+  lock: typeof lock;
+  /** Send a message to a named BroadcastChannel. */
+  broadcast(name: string, payload: any): void;
+  /** Subscribe to a named BroadcastChannel. Returns a dispose function. */
+  subscribe(name: string, fn: (msg: any) => void, signal?: AbortSignal): () => void;
+  /** Transfer a canvas to a worker. Returns a Promise<Offscreen>. */
+  offscreen(canvas: HTMLCanvasElement, script: string, opts?: OffscreenOptions): Promise<Offscreen>;
+  /** Terminate the pool for one script and remove it. */
+  close(script: string): void;
+  /** Terminate all pools and clear all broadcasts. */
+  clear(): void;
+};