ranuts 0.3.0-alpha.1 → 0.4.0-alpha.2

package/dist/src/utils/paginate.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Paginate plain text into fixed-size boxes — the layout a reader, a teleprompter or a
+ * printable preview needs, where the same text must be cut into pages of a known size.
+ *
+ * The whole thing is **pure arithmetic**: it takes the box dimensions and the type metrics as
+ * numbers and never touches the DOM. That is what lets it run inside a Worker, on the server,
+ * or in a test — measure the container once on the main thread, then paginate anywhere.
+ *
+ * It assumes a **monospaced grid**: every character advances either one cell (CJK, full-width)
+ * or `narrowRatio` of one (ASCII). That is exactly true for a monospaced font and close enough
+ * for the CJK-dominant body text this was built for; it is *not* a substitute for real shaping
+ * on proportional Latin text.
+ */
+/** The box each page must fit into, in px. */
+export interface TextBox {
+    width: number;
+    height: number;
+}
+export interface TextGridMetrics {
+    /** Advance width of one full-width character, px (font size + letter spacing). */
+    charWidth: number;
+    /** Distance between baselines, px. */
+    lineHeight: number;
+    /**
+     * Advance of a narrow (ASCII) character as a fraction of `charWidth`. Default `0.5625`
+     * (9/16), the usual half-width-plus-spacing ratio.
+     */
+    narrowRatio?: number;
+}
+export interface PaginateOptions {
+    /**
+     * Below this, in either dimension, the box is treated as not yet laid out and pagination
+     * returns nothing. Default `30`. Guards against paginating during first paint, when a
+     * container still measures 0 and a naive `floor(0 / charWidth)` would loop forever.
+     */
+    minBox?: number;
+}
+export interface TextPage {
+    text: string;
+    /** Offset of this page's first character in the source text. */
+    start: number;
+    /** Offset one past this page's last character. */
+    end: number;
+    index: number;
+}
+export interface PaginateResult {
+    pages: TextPage[];
+    /** Length of the normalized source text. */
+    total: number;
+    charsPerLine: number;
+    linesPerPage: number;
+    /** `charsPerLine * linesPerPage` — the budget one page spends. */
+    charsPerPage: number;
+}
+/**
+ * @description: Cut text into pages that fit `box`, given the type metrics.
+ *
+ * ASCII words are kept whole: a page never ends mid-word unless the word is longer than a
+ * line. Newlines start a new line and are charged one character.
+ *
+ * @param {string} text source text; `\r\n` / `\r` are normalized to `\n` first
+ * @param {TextBox} box page box in px — measure the container once, then call this anywhere
+ * @param {TextGridMetrics} metrics character advance and line height, px
+ * @param {PaginateOptions} options
+ * @return {PaginateResult} pages plus the grid it derived
+ * @example
+ * ```ts
+ * const { width, height } = container.getBoundingClientRect();
+ * const result = paginateText(book, { width, height }, { charWidth: 18.4, lineHeight: 40 });
+ * render(result.pages[0].text);
+ * ```
+ */
+export declare const paginateText: (text: string, box: TextBox, metrics: TextGridMetrics, options?: PaginateOptions) => PaginateResult;

package/dist/src/utils/speech.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Speech recognition (dictation) over the Web Speech API.
+ *
+ * This is the counterpart to `AudioRecorder`, which captures audio *bytes*; this one asks the
+ * platform to turn speech into *text*. The browser API is still prefixed on WebKit, is absent
+ * from `lib.dom`, and reports several routine non-events (a silent pause, a programmatic stop)
+ * through the same error channel as a denied microphone — so it is worth wrapping once.
+ */
+/**
+ * `denied` means the user or the browser refused the microphone — worth surfacing.
+ * `noSpeech` and `aborted` are routine (a silent pause, a programmatic `stop()`) and are
+ * usually not worth showing anyone; they are reported rather than swallowed so the caller
+ * decides. Everything else is `failed`.
+ */
+export type SpeechErrorKind = 'denied' | 'noSpeech' | 'aborted' | 'failed';
+export interface SpeechError {
+    kind: SpeechErrorKind;
+    /** The raw `error` string from the platform event. */
+    detail: string;
+}
+export interface SpeechRecognizerOptions {
+    /**
+     * BCP 47 tag for the language being spoken, e.g. `'en-US'`, `'zh-CN'`. Pass a function to
+     * have it read at the start of each capture, which is what an app whose UI language can
+     * change mid-session wants.
+     */
+    lang?: string | (() => string);
+    /** Keep listening across pauses instead of stopping at the first one. Default `true`. */
+    continuous?: boolean;
+    /** Emit partial results as the speaker talks. Default `true`. */
+    interimResults?: boolean;
+    /**
+     * Called as text arrives, with the transcript of the **whole capture so far** — not just
+     * the newest fragment — because interim results are revised as recognition firms up.
+     */
+    onResult?: (transcript: string, isFinal: boolean) => void;
+    onError?: (error: SpeechError) => void;
+    onStart?: () => void;
+    /** Fires once per capture, however it ended: stopped, timed out, or errored. */
+    onEnd?: () => void;
+}
+export interface SpeechRecognizer {
+    /** `false` when the platform has no speech recognition; every method is then a no-op. */
+    readonly supported: boolean;
+    /** Whether a capture is currently running. */
+    readonly active: boolean;
+    /** Begin a capture. Ignored if one is already running. */
+    start(): void;
+    /** End the current capture; results already recognized are kept. `onEnd` follows. */
+    stop(): void;
+    /** End the current capture and discard pending results. */
+    abort(): void;
+    /** Start if idle, stop if running — the behaviour a single microphone button wants. */
+    toggle(): void;
+}
+/**
+ * @description: Whether this runtime can recognize speech. Checked at call time, so it is safe
+ * to import this module during server-side rendering.
+ * @return {boolean}
+ */
+export declare const isSpeechRecognitionSupported: () => boolean;
+/**
+ * @description: Create a dictation session over the Web Speech API.
+ *
+ * A recognizer is reusable: `start` builds a fresh native instance each time, so options read
+ * through a function (notably `lang`) are re-read per capture.
+ *
+ * On a platform without speech recognition this returns an inert recognizer with
+ * `supported === false` rather than throwing — check that field to hide your microphone button.
+ *
+ * @param {SpeechRecognizerOptions} options
+ * @return {SpeechRecognizer}
+ * @example
+ * ```ts
+ * const mic = createSpeechRecognizer({
+ *   lang: () => currentLocale(),
+ *   onResult: (text) => { input.value = text; },
+ *   onError: (e) => { if (e.kind === 'denied') toast('Microphone access was refused'); },
+ *   onEnd: () => button.classList.remove('recording'),
+ *   onStart: () => button.classList.add('recording'),
+ * });
+ * if (!mic.supported) button.style.display = 'none';
+ * button.addEventListener('click', () => mic.toggle());
+ * ```
+ */
+export declare const createSpeechRecognizer: (options?: SpeechRecognizerOptions) => SpeechRecognizer;

package/dist/src/utils/str.d.ts

@@ -64,6 +64,41 @@ export declare const toHalfWidth: (value: string) => string;
  * @return {string}
  */
 export declare const toFullWidth: (value: string) => string;
+/** Which end of the string gets dropped when it is too long. */
+export type TruncatePosition = 'end' | 'start' | 'middle';
+export interface TruncateOptions {
+    /** Ceiling for the returned string, ellipsis included. */
+    length: number;
+    /** Default `'end'`. */
+    position?: TruncatePosition;
+    /** Default `'…'`. */
+    ellipsis?: string;
+}
+/**
+ * @description: Shorten a string to a maximum length, marking the cut with an ellipsis.
+ *
+ * `position` decides which end survives, and that choice carries real information:
+ *
+ * - `'end'` (default) keeps the beginning — right for prose and titles.
+ * - `'start'` keeps the **tail**, which is what a file path wants. `/Users/someone/work/…`
+ *   are the bytes a reader already knows; `…/src/utils/str.ts` is the part they need.
+ * - `'middle'` keeps both ends, for identifiers whose head *and* tail are meaningful, such as
+ *   a hash or an account number.
+ *
+ * The result never exceeds `length`, so a `length` shorter than the ellipsis returns a
+ * truncated ellipsis rather than overflowing.
+ *
+ * @param {string} value
+ * @param {TruncateOptions | number} options a bare number is shorthand for `{ length }`
+ * @return {string}
+ * @example
+ * ```ts
+ * truncate('the quick brown fox', 12);                                 // 'the quick b…'
+ * truncate('/Users/me/code/app/src/index.ts', { length: 20, position: 'start' }); // '…de/app/src/index.ts'
+ * truncate('0xabcdef0123456789', { length: 11, position: 'middle' });   // '0xabc…56789'
+ * ```
+ */
+export declare const truncate: (value: string, options: TruncateOptions | number) => string;
 export interface TransformText {
     encoding: string;
     content: string;

package/dist/src/utils/time.d.ts

@@ -1,3 +1,5 @@
+/** Accepted everywhere a moment in time is taken; `undefined` means "now". */
+export type DateInput = number | string | Date;
 /**
  * @description: Format a date with a token pattern. Accepts a timestamp, a date string, a
  * `Date`, or nothing (meaning now). Wrap literal text in `[]` to keep it out of the substitution.
@@ -23,10 +25,10 @@
  * ```ts
  * formatDate();                                          // '2026-07-25 14:30:00'
  * formatDate(1753425000000, 'YYYY/MM/DD');               // '2026/07/25'
- * formatDate(new Date(), 'YYYY[年]MM[月]DD[日] hh:mm a'); // '2026年07月25日 02:30 pm' (escaped literals)
+ * formatDate(new Date(), 'YYYY[年]MM[月]DD[日] hh:mm a'); // '2026 年 07 月 25 日 02:30 pm' (escaped literals)
  * ```
  */
-export declare const formatDate: (value?: number | string | Date, pattern?: string) => string;
+export declare const formatDate: (value?: DateInput, pattern?: string) => string;
 /**
  * @description: Turn a timestamp into a `Date` carrying a `format` method.
  * @deprecated Use [`formatDate`](#formatdate). This returns a `Date` with an extra method
@@ -39,12 +41,80 @@ export declare const formatDate: (value?: number | string | Date, pattern?: stri
 export declare function timestampToTime(timestamp?: number | string): Date & {
     format?: Function;
 };
+/**
+ * @description: Format an elapsed number of **seconds** as a colon-separated clock duration,
+ * the shape media players use for a playhead: `mm:ss`, widening to `hh:mm:ss` past an hour.
+ *
+ * This is a length of time, not a point in time — for the latter see
+ * [`formatDate`](#formatdate) (absolute) and [`formatRelative`](#formatrelative) (relative).
+ *
+ * @param {number} seconds elapsed seconds; negatives clamp to `0`
+ * @return {string} the duration, or `''` when the input is not a finite number — a player
+ * asks for `video.duration` before metadata loads and gets `NaN`, and an empty label reads
+ * better there than `NaN:NaN`
+ * @example
+ * ```ts
+ * formatDuration(0);    // '00:00'
+ * formatDuration(65);   // '01:05'
+ * formatDuration(3661); // '01:01:01'
+ * formatDuration(NaN);  // ''
+ * ```
+ */
+export declare const formatDuration: (seconds: number) => string;
 /**
  * @description: Format a number of seconds as a colon-separated duration
+ * @deprecated Renamed to [`formatDuration`](#formatduration) — `timeFormat` said nothing about
+ * *which* of the three time formats it was, and read backwards from its `formatDate` sibling.
+ * This alias stays for compatibility and behaves identically.
  * @param {number} time
- * @return {*}
+ * @return {string}
  */
 export declare const timeFormat: (time: number) => string;
+/** `'compact'` is ours; the other three are `Intl.RelativeTimeFormat` styles. */
+export type RelativeStyle = 'long' | 'short' | 'narrow' | 'compact';
+export interface FormatRelativeOptions {
+    /** What to measure against. Defaults to the current time. */
+    now?: DateInput;
+    /** BCP 47 tag(s); defaults to the runtime's locale. Ignored by the `compact` style. */
+    locale?: string | string[];
+    /** Defaults to `'long'` (`'3 days ago'`). */
+    style?: RelativeStyle;
+    /**
+     * `'auto'` (the default here) swaps in idioms where a language has them — `yesterday`
+     * rather than `1 day ago`, `now` rather than `in 0 seconds`. `'always'` keeps the number.
+     */
+    numeric?: 'always' | 'auto';
+}
+/**
+ * @description: Format a point in time relative to another — "3 days ago", "in 2 hours".
+ *
+ * Localization is delegated to the platform's `Intl.RelativeTimeFormat`, which has been
+ * available in every major browser since 2020 and knows each language's plural and
+ * inflection rules. This function supplies only the part `Intl` deliberately leaves out:
+ * picking *which* unit to express the gap in.
+ *
+ * Like `Intl` itself it reports a **single** unit — a gap of 3 days and 6 hours is
+ * "3 days ago", never "3 days and 6 hours ago".
+ *
+ * The extra `compact` style is the dense badge form seen next to list items (`5m`, `3h`,
+ * `2d`). It is a magnitude only: it carries **no direction**, so a future timestamp reads
+ * the same as a past one. Use it for feeds of past events, and any other style when the
+ * reader has to tell past from future.
+ *
+ * @param {DateInput} value the moment to describe
+ * @param {FormatRelativeOptions} options
+ * @return {string} the description, or `''` when either end cannot be parsed
+ * @example
+ * ```ts
+ * const twoHoursAgo = Date.now() - 2 * 3600_000;
+ * formatRelative(twoHoursAgo);                          // '2 hours ago'
+ * formatRelative(twoHoursAgo, { style: 'short' });      // '2 hr. ago'
+ * formatRelative(twoHoursAgo, { style: 'compact' });    // '2h'
+ * formatRelative(twoHoursAgo, { locale: 'zh-CN' });     // '2 小时前'
+ * formatRelative(Date.now() + 60_000);                  // 'in 1 minute'
+ * ```
+ */
+export declare const formatRelative: (value: DateInput, options?: FormatRelativeOptions) => string;
 /**
  * @description: Current timestamp
  * @return {*}

package/dist/src/utils/worker.d.ts

@@ -74,3 +74,52 @@ export declare class WorkerClient<Req extends object, Res extends WorkerResponse
     private handleMessage;
     private rejectAll;
 }
+/** A request always carries the id the client stamped on it */
+export interface WorkerRequestBase {
+    operationId: number;
+    type?: string;
+}
+/** Handed to the handler so it can stream progress for the request it is currently serving */
+export interface WorkerHandlerContext<Progress> {
+    /** Post a progress update. Does not settle the request; may be called any number of times. */
+    progress: (payload: Progress) => void;
+}
+export interface ServeWorkerOptions {
+    /**
+     * Where to listen. Defaults to `self` — override for a `MessagePort`, a nested worker, or
+     * a test double.
+     */
+    scope?: {
+        addEventListener: (type: 'message', listener: (event: MessageEvent) => void) => void;
+        removeEventListener: (type: 'message', listener: (event: MessageEvent) => void) => void;
+        postMessage: (message: unknown, transfer?: Transferable[]) => void;
+    };
+    /** Response `type` for a successful reply that the handler returned bare (non-object). Default `'result'`. */
+    resultType?: string;
+}
+/**
+ * @description: Serve requests inside a Web Worker, mirroring {@link WorkerClient} on the
+ * other end. Reads `operationId` off each request, awaits your handler, and posts the reply
+ * back with that same id.
+ *
+ * Failures become `{ operationId, type: 'error', message }` — the envelope `WorkerClient`
+ * rejects on by default. **Both synchronous throws and rejected promises are caught**: a sync
+ * throw inside `onmessage` would otherwise escape to the worker's error handler, which carries
+ * no id, so the client could only fail *every* in-flight request instead of the one that broke.
+ *
+ * @param {Function} handler receives the request and a context whose `progress()` streams updates
+ * @param {ServeWorkerOptions} options
+ * @return {Function} stop — removes the listener
+ * @example
+ * ```ts
+ * // my.worker.ts
+ * serveWorker<MyRequest, MyResponse, ModelProgress>(async (request, { progress }) => {
+ *   if (request.type === 'load') {
+ *     const device = await load(request.modelId, (p) => progress(p));
+ *     return { type: 'loaded', device };
+ *   }
+ *   return { type: 'result', scores: await classify(request.lines) };
+ * });
+ * ```
+ */
+export declare const serveWorker: <Req extends WorkerRequestBase, Res extends object = object, Progress = unknown>(handler: (request: Req, context: WorkerHandlerContext<Progress>) => Promise<Res> | Res, options?: ServeWorkerOptions) => (() => void);

package/dist/test/sw.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/utils/autosize.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/utils/i18n.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/utils/idb-collection.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/utils/paginate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/utils/speech.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/utils/time.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/utils/truncate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/utils/worker-serve.test.d.ts

@@ -0,0 +1 @@
+export {};