independent-subtitle-parser 0.0.0-stage → 0.1.7

package/CHANGELOG.md

@@ -0,0 +1,98 @@
+# Changelog
+
+## 0.1.7 — legacy SAMI commands and large real ASS/SSA validation, unpublished
+
+- Connect the public GitHub source repository, issue/PR routes and npm repository
+  metadata. Prepare the public 0.1.7 manifest and registry/tarball installation
+  instructions; actual npm publication remains pending separate approval.
+- Prepare public-facing README, contribution/reporting guides and GitHub issue/PR
+  templates. Include contribution/reporting guides in the package. Add a separate
+  release package check for the public manifest.
+- Retain observed `SpanID`, `ShowImg` and `DisplayImg` authoring commands as opaque
+  `sami-legacy-command` metadata; exclude complete commands from reading text so
+  they cannot create phantom captions or prevent NBSP clears. Warn once with
+  `SAMI_LEGACY_COMMAND_UNAPPLIED`. No command effects are executed.
+- Recover incomplete commands at the next `<`; preserve their literal text and
+  diagnose malformed syntax. Quoted `>` and unquoted apostrophes are covered.
+- Add seven hash-pinned local evaluation files, including 7.6 MB and 5.9 MB ASS
+  animation-heavy originals and three long-form SSA v4 files. Independent
+  expectations cover every event's time/raw fields and a declared reading subset.
+- Score three previously unscored legacy SAMI files under a narrow nonspoken
+  command profile. Demo layout and interactive playback remain unscored.
+- See [scope, comparisons and reproduction](docs/CORPUS-017.md). No npm release
+  or product integration has been performed.
+
+## 0.1.6 — ASS/SSA/SAMI corpus validation, unpublished
+
+- Recover unpadded ASS minute/second fields with `ASS_TIME_WIDTH_RECOVERED`;
+  keep centisecond precision strict and preserve original event fields.
+- Read legacy SAMI `SAMI_Type` as well as `SAMIType` into track kind.
+- Warn once per document for unapplied SAMI Source ID speaker persistence;
+  retain its paragraph text and attributes without claiming layout support.
+- Add 18 pinned, licensed upstream ASS/SSA/SAMI originals and independent
+  source-derived oracles. Evaluate 19 additional local-only originals without
+  redistributing transcripts of uncertain license. Record unscored legacy
+  player commands separately from passing cases.
+- Expand the mutation corpus and current-runtime correctness, package and
+  performance checks. Keep `private: true`; no adapters or publication.
+
+## 0.1.5 — publication preparation, unpublished
+
+- Confirm the package name and apply the owner-selected MIT license to original
+  code. Keep `private: true` until a separately authorized publication.
+- Check actual archive bytes against source and installed files, verify npm
+  integrity, enforce the package allowlist and require repeatable tarball bytes.
+- Bound browser track options to 100 per page and shorten displayed labels;
+  all tracks remain selectable and complete results remain in JSON.
+- Add pinned, licensed libass and Microsoft WMP samples with independent
+  expectations, plus a reproducible external-writer integration comparison.
+- Expand fuzz seeds and clarify the remaining corpus and platform gaps.
+- Parser runtime and public API remain unchanged from 0.1.4. No adapters,
+  product changes or npm publication.
+
+## 0.1.4 — consumer usability iteration, unpublished
+
+- Reorganize README around installed-package use; move detailed contract to API
+  reference and add diagnostic, usage and development guides.
+- Include runnable Node and browser file examples in the tarball. Browser parsing
+  runs in a disposable Worker with cancel/deadline/stale-result handling, explicit
+  encoding/format choices, track selection, labeled previews and complete JSON.
+- Keep decode and parse diagnostics distinct, unknown cue ends unchanged, and
+  text output inert. No file upload, storage, charset guessing or rendering.
+- Retain the existing public API and TypeScript interfaces; workflow helpers are
+  consumer recipes, not package exports. Parser source is unchanged from 0.1.3.
+- Correct stale documentation about the already completed product comparison.
+- Preserve historical quality evidence; no product adapters or npm publication.
+
+## 0.1.3 — corpus and robustness iteration, unpublished
+
+- Fix WebVTT missing-separator recovery assigning header metadata as a cue ID.
+- Recover SRT single-dash arrows and one terminal period after a complete comma
+  end timestamp, with dedicated warnings and exact source retention. These occur
+  in Blender's published Portuguese and Indonesian subtitles.
+- Diagnose preserved unterminated WebVTT markup instead of returning clean status.
+- Correct windows-1252 C1 characters on affected Node/ICU decoders using the
+  WHATWG mapping; aliases resolve through TextDecoder. Other encodings remain
+  runtime-dependent. No charset detection was introduced.
+- Avoid the SAMI markup scanner for plain paragraphs and gaps while preserving
+  HTML ASCII whitespace and non-ASCII spaces.
+- Add pinned WPT and licensed Blender corpus, six OSS comparison targets,
+  isolated performance/memory harnesses and reproducible sustained fuzzing.
+- Test Node 20 and 24 plus Chromium. Evidence and remaining limits are recorded
+  in the local `evidence/quality-013-final/REPORT.md` and `docs/CORPUS.md`.
+- No adapters, product changes, runtime dependencies or publication.
+
+## 0.1.2 — local quality iteration, unpublished
+
+- Fix valid WebVTT class names containing Unicode spaces and voice annotations
+  containing a literal `<`. Preserve the original tag in raw text and fields.
+- Add 19 focused text regressions and generated arithmetic, newline, Unicode
+  decode and malformed-content invariant checks.
+- Define evidence-based public npm release gates and defer product adapters.
+- No public API shape changes. Existing 0.1.0/0.1.1 and product-comparison evidence
+  remains unchanged. Full WebVTT semantic trees and ASS rendering remain absent.
+
+## 0.1.1 — unpublished
+
+See `docs/IMPROVEMENTS.md` and the frozen `evidence/improvements-1/REPORT.md` in
+the local source workspace for the original improvement record.

package/CONTRIBUTING.md

@@ -0,0 +1,81 @@
+# Contributing
+
+Contributions can improve parsing, independent test expectations, documentation
+or consumer examples. Keep changes focused on the documented extraction profile.
+Please explain the input that fails and the behavior your change establishes.
+
+The canonical repository is
+[saramkim/independent-subtitle-parser](https://github.com/saramkim/independent-subtitle-parser).
+Use [Issues](https://github.com/saramkim/independent-subtitle-parser/issues) for
+reports and proposals. Fork the repository, make a focused branch, then open a
+[pull request](https://github.com/saramkim/independent-subtitle-parser/pulls)
+against `main`. See [Reporting bugs](docs/REPORTING.md). No response time is promised.
+
+## Set up a source checkout
+
+Use Node.js 20+ and npm. Package validation also uses `tar` from PATH.
+Runtime dependencies remain empty; TypeScript is a development dependency.
+
+```sh
+npm ci --ignore-scripts
+npm run build
+npm test
+```
+
+For a focused change, build and run the relevant test file first:
+
+```sh
+npm run build
+node --test test/sami.test.mjs
+```
+
+Before proposing a finished patch, run `npm run validate`. It builds the package,
+runs the suite, installs/checks the real tarball, runs the Node example and records
+a benchmark. Evidence is written to a fresh ignored directory. See the
+[development guide](docs/DEVELOPMENT.md) for custom output paths and PowerShell.
+Do not label an unexecuted platform/browser check as passed. For documentation
+changes, validate changed examples and package links; unrelated long fuzz
+campaigns need not be rerun when their runtime inputs are unchanged.
+
+## Establish the expected result independently
+
+- Cite a public format specification or a clearly described compatibility policy.
+  For real files, record provenance, encoding, revision and SHA-256.
+- Add the smallest useful reproduction. Preserve the original failing case and
+  show that the proposed fix changes it for the stated reason.
+- Do not change an expected value merely because this parser or another library
+  returns something else. Explain disagreements and distinguish parsing from
+  rendering, raw preservation from text projection, and recovery from conformance.
+- Test important effects on times, line breaks, raw/source text, tracks, fields,
+  diagnostics and resource limits. Include malformed variants when relevant.
+
+Tests are in `test/`; runtime code is in `src/`; examples are host applications
+in `examples/`. The public API is the package root. Keep the core independent of
+UI, DOM, filesystem, storage and extension APIs. Full ASS rendering, streaming
+and serialization are outside the current scope. Discuss substantial API or
+dependency changes with maintainers before investing in a large patch.
+
+## Fixtures, privacy and licensing
+
+Prefer a small synthetic subtitle that you wrote. Do not commit private captions,
+full copyrighted transcripts, credentials, local account paths or personal data.
+An open-source repository's code license does not necessarily license subtitles,
+fonts or images stored beside its code. Third-party fixtures need a verified
+redistribution basis, attribution and provenance; retain their original licenses.
+If rights are unclear, use a synthetic reproduction or record public provenance
+for optional local evaluation. See [corpus methodology](docs/CORPUS.md).
+
+Preserve fixture bytes, BOM and line endings. `.gitattributes` intentionally
+disables automatic newline conversion. Do not bulk-format corpus files.
+Keep generated `dist/`, tarballs, dependencies, caches and local `evidence/` out
+of commits. Original code contributions are provided under the project's
+[MIT license](LICENSE); retain applicable third-party notices.
+
+## Submit a focused change
+
+Describe the problem, independent expected behavior, final change and checks
+actually run. Mention API/diagnostic changes and known limitations. Update the
+changelog and user-facing documentation when behavior changes. Use the prepared
+PR template when opening a pull request. Publishing a package or
+changing release credentials is a separate maintainer action, not a contribution
+requirement. Be respectful and keep disagreements tied to reproducible evidence.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 independent-subtitle-parser contributors
+
+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

@@ -1,3 +1,195 @@
-# Temporary Holding Version
+# Independent Subtitle Parser
 
-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.
+[![CI](https://github.com/saramkim/independent-subtitle-parser/actions/workflows/ci.yml/badge.svg)](https://github.com/saramkim/independent-subtitle-parser/actions/workflows/ci.yml)
+
+Parse **SRT, WebVTT, SAMI/SMI and ASS/SSA** with one TypeScript API in browsers
+and Node.js. Extract timed text and language tracks while keeping the source,
+raw markup and diagnostics available for inspection.
+
+- **One data model:** millisecond timestamps, readable text, tracks and metadata.
+- **Explicit recovery:** malformed input, omitted data and unsupported presentation
+  produce diagnostics instead of silently disappearing.
+- **Portable core:** no runtime dependencies, DOM, storage, network access or renderer.
+
+Use it for subtitle import, inspection, search and text-based playback workflows.
+For styled ASS playback, use a dedicated renderer alongside the preserved source.
+
+## Install
+
+Registry installation (requires a published version):
+
+```sh
+npm install independent-subtitle-parser
+```
+
+For an unpublished release candidate, install the supplied tarball instead:
+
+```sh
+npm install ./independent-subtitle-parser-0.1.7.tgz
+```
+
+To build that tarball from a source checkout:
+
+```sh
+git clone https://github.com/saramkim/independent-subtitle-parser.git
+cd independent-subtitle-parser
+npm ci --ignore-scripts
+npm pack
+```
+
+Node.js **20+**; ESM with TypeScript declarations. CommonJS callers use dynamic
+`import()`; synchronous `require()` is not a supported export. Browser consumers
+need ES2022, and `TextDecoder` when decoding bytes. Import the package root through
+your application's module/bundler setup; the examples also run without a bundler.
+
+## Quick start
+
+```ts
+import { parse } from 'independent-subtitle-parser';
+
+const source = '1\n00:00:01,250 --> 00:00:03,000\n안녕하세요\nHello';
+const result = parse(source);
+
+if (result.status === 'fatal') {
+  console.error(result.diagnostics); // no cues, tracks or metadata returned
+} else {
+  console.log(result.cues[0]?.start); // 1250 (milliseconds)
+  console.log(result.cues[0]?.end);   // 3000
+  console.log(result.cues[0]?.text);  // 안녕하세요\nHello
+  console.log(result.diagnostics);   // inspect partial results too
+}
+```
+
+`parse` detects the format from content. If the format is already known, pass
+`parse(source, { format: 'sami' })`; `.smi` files use the `sami` option.
+`detectFormat(source)` exposes the detection result without parsing cues.
+
+## Supported formats
+
+| Format | Extracted and preserved | Important limits |
+| --- | --- | --- |
+| SRT | Times, IDs, multiline text and raw markup; diagnosed recovery of common malformed syntax | No universal SRT standard or styling renderer; ambiguous damage can remain unrecovered |
+| WebVTT | Times, IDs, cue settings, text/voice/language markup and NOTE/STYLE/REGION metadata | No browser layout/CSS engine; HLS timestamp mapping is retained but not applied |
+| SAMI/SMI | SYNC times, class/language tracks, clear events, BR/PRE and legacy authoring-command metadata | Final end can be unknown; no full HTML/CSS layout, Source panel or command execution |
+| ASS/SSA | Dialogue, centisecond times, event fields, styles/comments, raw overrides and a reading-text projection | No fonts, positioning, drawings or karaoke rendering; declared Timer scaling is not applied |
+
+See the [complete support profile](docs/API.md) for recovery rules and unsupported
+syntax. Source order, overlaps and duplicates are retained. The library does not
+sort cues, infer languages, merge tracks or choose a playback track for you.
+
+## Work with results
+
+| Value | Meaning |
+| --- | --- |
+| `status: 'ok'` | No warning/error in the supported extraction profile; not a full conformance certificate |
+| `status: 'partial'` | Usable data may coexist with recovery, omitted data or unsupported presentation; inspect diagnostics |
+| `status: 'fatal'` | No cues/tracks/metadata; diagnostics and source remain available |
+| `end: null` | No reliable end is known; your application must choose an explicit playback policy |
+
+`text` is a reading projection. `rawText` retains cue markup with LF-normalized
+line endings. `sourceText` is the exact string passed to `parse`. Keep original
+bytes separately for byte-perfect archival. Render output as text, never raw
+`innerHTML`. A warning about unapplied styling does not necessarily mean that a
+caption was lost. The [diagnostic guide](docs/DIAGNOSTICS.md) explains decisions.
+
+For multilingual subtitles, inspect `result.tracks`, let the caller choose a
+track ID, then filter `result.cues` by `cue.trackId`.
+[Track-selection recipes](docs/USAGE.md) cover missing language metadata and
+unknown end times.
+
+## Decode file bytes
+
+Decoding is separate from parsing. `decode` defaults to UTF-8 or a UTF-8/UTF-16
+BOM; it does **not** guess legacy encodings. Supply a known encoding such as
+`euc-kr`. Invalid byte sequences fail by default.
+
+```ts
+import { decode, parse } from 'independent-subtitle-parser';
+
+function readSubtitle(bytes: Uint8Array, encoding?: string) {
+  const decoded = decode(bytes, { encoding });
+  const parsed = decoded.text === null ? null : parse(decoded.text);
+  return { decoded, parsed }; // retain diagnostics from both stages
+}
+
+// Browser: readSubtitle(new Uint8Array(await file.arrayBuffer()))
+// Node: readSubtitle(await readFile(path)) from node:fs/promises
+// Legacy encoding: readSubtitle(bytes, 'euc-kr')
+```
+
+Check file size **before** reading it. Default decoding accepts up to 16 MiB;
+parsing has separate string, line, cue and diagnostic budgets. Replacement
+decoding (`fatal: false`) is an explicit lossy choice: retain its warning even
+when parsing succeeds. Invalid API options throw `TypeError` or `RangeError`;
+file-content problems return diagnostics. Catch host I/O errors separately.
+
+The API is synchronous and reads a whole document. Large results and JSON export
+consume memory. For untrusted files or responsive UI, use lower
+[resource budgets](docs/API.md) and a host-managed Worker/process with a deadline.
+
+## Try a real file
+
+The package includes runnable examples. From an application with the package
+installed:
+
+```sh
+node node_modules/independent-subtitle-parser/examples/node.mjs ./movie.srt
+node node_modules/independent-subtitle-parser/examples/node.mjs ./movie.smi euc-kr sami
+node node_modules/independent-subtitle-parser/examples/serve.mjs
+```
+
+The Node example writes the complete result as JSON. The server prints a local
+URL for the browser example, which provides file/encoding/format selection,
+track previews, diagnostics, JSON download and a cancellable module Worker.
+File contents are not uploaded or stored. Preview limits do not truncate the
+retained parse result. Serve over HTTP; `file:` does not reliably load modules.
+
+In a source checkout, run `npm run build`, then `node examples/node.mjs` or
+`node examples/serve.mjs`. See [consumer recipes](docs/USAGE.md) for CommonJS,
+bundlers, Worker lifetime and CLI exit codes.
+
+## Validation and compatibility
+
+[Hosted CI](docs/CI.md) passed **412 tests in each of nine jobs**: Node 20, 22 and
+24 on Windows, Ubuntu and macOS. Package checks install the actual tarball and
+check imports, TypeScript declarations, examples and archive byte identity.
+Local Chromium 156 also passed 16 consumer scenarios on Windows. The Node CI
+matrix does not certify native browser behavior: the current runtime has not
+been revalidated in Firefox/Safari or in browsers on the other operating systems.
+
+The latest corpus expansion checked 23,889 events in seven real ASS/SSA files
+for timing, raw text and fields; reading text was scored on a restricted 5,107
+events. Three legacy SAMI files were checked separately. A ten-minute seeded
+campaign completed 3,655,680 mutations and 456,960 arithmetic cases, with another
+896 mutations on full-size original files. These are bounded checks, not proof
+of perfection, full rendering conformance or superiority over every parser.
+
+Reproduce the standard checks in a source checkout with `npm run validate`.
+[Corpus methodology](docs/CORPUS.md), [the latest evaluation](docs/CORPUS-017.md)
+and [quality criteria](docs/QUALITY.md) explain sources, licenses, comparisons,
+unscored cases and reproduction commands. Historical local evidence archives
+are not included in Git or npm.
+
+## Contribute and report bugs
+
+Small reproductions, corrections to format interpretation, documentation and
+tests are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) for setup and expected
+evidence, and [Reporting bugs](docs/REPORTING.md) for the report checklist.
+Use the [public source repository](https://github.com/saramkim/independent-subtitle-parser),
+[bug report form](https://github.com/saramkim/independent-subtitle-parser/issues/new?template=bug_report.yml)
+and [pull requests](https://github.com/saramkim/independent-subtitle-parser/pulls).
+
+During 0.x, review the [changelog](CHANGELOG.md) when upgrading and pin the
+version you have validated. New diagnostics and recovery behavior can affect
+consumer decisions. Full rendering, serialization, streaming and automatic
+charset guessing remain outside this package's current scope.
+
+## License and documentation
+
+Original package code is licensed under [MIT](LICENSE). Third-party reference
+data retains its own licenses; see [third-party notices](THIRD_PARTY_NOTICES.md).
+
+- [API reference](docs/API.md) and [diagnostic guide](docs/DIAGNOSTICS.md)
+- [Usage recipes](docs/USAGE.md) and [development guide](docs/DEVELOPMENT.md)
+- [Design](docs/DESIGN.md), [public format sources](docs/SOURCES.md) and [changelog](CHANGELOG.md)
+- [Release checklist for maintainers](docs/RELEASE.md)

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,60 @@
+# WHATWG HTML named character reference data
+
+Original parser code is under the MIT license in `LICENSE`. This does not
+relicense third-party data. Additional development-only fixtures in
+`corpus/release-015/` are from libass (ISC; local `libass/COPYING`) and Microsoft
+Windows-classic-samples (MIT; local `microsoft/LICENSE`), with exact revisions,
+URLs and hashes in that directory's manifest. These fixtures are not in the
+npm tarball. The external sample/writer provenance and coverage limits are
+documented in `docs/RELEASE.md`.
+
+Development-only `corpus/corpus-016/` adds unchanged authored samples from
+Arnavion/libjass (Apache-2.0), subtitle-rs/subtitler (Apache-2.0), and
+SubtitleEdit/subtitleedit (MIT). Each upstream license is retained alongside
+its samples; `manifest.json` pins revisions, original URLs and SHA-256 hashes.
+No upstream parser implementation, font or image is incorporated. These samples
+and licenses are excluded from the npm tarball. Additional downloaded originals
+with uncertain transcript redistribution rights remain in ignored local caches;
+their metadata alone is in `research/corpus-016/local-manifest.json`.
+
+Development-only corpus: WPT files retain their BSD-3-Clause notice in
+`corpus/wpt/LICENSE.md`. *Tears of Steel* subtitles are attributed to
+**(CC) Blender Foundation | mango.blender.org** and volunteer translators under
+CC BY 3.0 (https://creativecommons.org/licenses/by/3.0/), with unchanged original
+files and provenance documented in `docs/CORPUS.md`. Corpus and comparison
+dependencies are not shipped in the npm tarball. No third-party parser code is
+incorporated into the runtime. The small windows-1252 mapping in `decode.ts` is
+standard character data from https://encoding.spec.whatwg.org/index-windows-1252.txt
+under WHATWG's BSD terms reproduced below.
+
+`entities.reference.json` was retrieved on 2026-10-23 from
+https://html.spec.whatwg.org/entities.json . `src/entities.ts` is a mechanical
+projection of the names and Unicode values. No parser code
+was copied. `scripts/generate-entities.mjs` reproduces that projection.
+
+Copyright © WHATWG (Apple, Google, Mozilla, Microsoft).
+The HTML standard portions incorporated into source code use the BSD 3-Clause
+License, per https://whatwg.org/ipr-policy#copyright-license-for-whatwg-publications .
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software without
+   specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/dist/context.d.ts

@@ -0,0 +1,22 @@
+import type { Cue, Limits, MetadataBlock, ParseResult, Severity, SubtitleFormat, Track } from './types.js';
+export declare const DEFAULT_LIMITS: Readonly<Limits>;
+export declare class ParseAbort extends Error {
+}
+export declare class ParseContext {
+    readonly format: SubtitleFormat;
+    readonly limits: Limits;
+    readonly cues: Cue[];
+    readonly tracks: Track[];
+    readonly metadata: MetadataBlock[];
+    private problem;
+    private truncated;
+    private readonly infoCodes;
+    private readonly diagnosticBuckets;
+    private diagnosticCount;
+    private diagnosticOrder;
+    constructor(format: SubtitleFormat, limits: Limits);
+    diagnostic(code: string, severity: Severity, message: string, line?: number): void;
+    fatal(code: string, message: string, line?: number): never;
+    addCue(cue: Cue): boolean;
+    result(sourceText: string, fatal?: boolean): ParseResult;
+}

package/dist/context.js

@@ -0,0 +1,70 @@
+export const DEFAULT_LIMITS = Object.freeze({
+    maxInputLength: 8 * 1024 * 1024, maxLines: 250_000, maxLineLength: 1024 * 1024,
+    maxCues: 100_000, maxDiagnostics: 1_000,
+});
+export class ParseAbort extends Error {
+}
+const severityRank = { info: 0, warning: 1, error: 2, fatal: 3 };
+export class ParseContext {
+    format;
+    limits;
+    cues = [];
+    tracks = [];
+    metadata = [];
+    problem = false;
+    truncated = false;
+    infoCodes = new Set();
+    diagnosticBuckets = [[], [], [], []];
+    diagnosticCount = 0;
+    diagnosticOrder = 0;
+    constructor(format, limits) {
+        this.format = format;
+        this.limits = limits;
+    }
+    diagnostic(code, severity, message, line) {
+        if (severity === 'info') {
+            if (this.infoCodes.has(code))
+                return;
+            this.infoCodes.add(code);
+        }
+        if (severity === 'warning' || severity === 'error' || severity === 'fatal')
+            this.problem = true;
+        const rank = severityRank[severity];
+        if (this.diagnosticCount >= this.limits.maxDiagnostics) {
+            this.truncated = true;
+            this.problem = true;
+            // Four fixed buckets keep overflow work O(1), even for large budgets.
+            const lowest = this.diagnosticBuckets.findIndex(bucket => bucket.length > 0);
+            if (rank <= lowest && severity !== 'fatal')
+                return;
+            // Keep earlier diagnostics at equal severity; replace the newest member
+            // of a lower severity when an actionable cause arrives.
+            this.diagnosticBuckets[lowest].pop();
+        }
+        else
+            this.diagnosticCount++;
+        const diagnostic = { code, severity, message, ...(line === undefined ? {} : { line }) };
+        this.diagnosticBuckets[rank].push({ diagnostic, order: this.diagnosticOrder++ });
+    }
+    fatal(code, message, line) {
+        this.diagnostic(code, 'fatal', message, line);
+        throw new ParseAbort(message);
+    }
+    addCue(cue) {
+        if (!Number.isSafeInteger(cue.start) || cue.start < 0 ||
+            (cue.end !== null && (!Number.isSafeInteger(cue.end) || cue.end <= cue.start))) {
+            this.diagnostic('INVALID_INTERVAL', 'error', 'Cue requires safe nonnegative integer milliseconds and end greater than start.', cue.source.line);
+            return false;
+        }
+        if (this.cues.length >= this.limits.maxCues)
+            this.fatal('CUE_LIMIT', 'Cue count exceeds maxCues.', cue.source.line);
+        this.cues.push(cue);
+        return true;
+    }
+    result(sourceText, fatal = false) {
+        const diagnostics = this.diagnosticBuckets.flat().sort((a, b) => a.order - b.order).map(entry => entry.diagnostic);
+        return { format: this.format, status: fatal ? 'fatal' : this.problem ? 'partial' : 'ok',
+            cues: fatal ? [] : this.cues, tracks: fatal ? [] : this.tracks,
+            metadata: fatal ? [] : this.metadata, diagnostics, diagnosticsTruncated: this.truncated, sourceText };
+    }
+}

package/dist/decode.d.ts

@@ -0,0 +1,3 @@
+import type { DecodeOptions, DecodeResult } from './types.js';
+/** Explicit byte decoding, independent of subtitle format and file/network I/O. */
+export declare function decode(bytes: Uint8Array, options?: DecodeOptions): DecodeResult;

package/dist/decode.js

@@ -0,0 +1,51 @@
+// Intrinsic getters inspect internal typed-array slots across realms. Object#toString
+// and an object's public byteLength can both be overridden by callers.
+const typedArrayPrototype = Object.getPrototypeOf(Uint8Array.prototype);
+const typedArrayName = Object.getOwnPropertyDescriptor(typedArrayPrototype, Symbol.toStringTag).get;
+const typedArrayByteLength = Object.getOwnPropertyDescriptor(typedArrayPrototype, 'byteLength').get;
+// WHATWG windows-1252 index entries 0..31 (bytes 0x80..0x9f).
+// Some Node/ICU versions incorrectly return Latin-1 controls for these bytes.
+// A conforming decoder's five literal C1 controls map to themselves here.
+const WINDOWS_1252_C1 = '€\u0081‚ƒ„…†‡ˆ‰Š‹Œ\u008dŽ\u008f\u0090‘’“”•–—˜™š›œ\u009džŸ';
+/** Explicit byte decoding, independent of subtitle format and file/network I/O. */
+export function decode(bytes, options = {}) {
+    if (!ArrayBuffer.isView(bytes) || typedArrayName.call(bytes) !== 'Uint8Array')
+        throw new TypeError('decode expects Uint8Array.');
+    const maxBytes = options.maxBytes ?? 16 * 1024 * 1024;
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1)
+        throw new RangeError('maxBytes must be a positive safe integer.');
+    if (options.fatal !== undefined && typeof options.fatal !== 'boolean')
+        throw new TypeError('fatal must be boolean.');
+    const diagnostics = [];
+    const fail = (code, message, encoding = null, bom = null) => ({ text: null, encoding, bom, diagnostics: [...diagnostics, { code, severity: 'fatal', message }] });
+    if (typedArrayByteLength.call(bytes) > maxBytes)
+        return fail('BYTE_LIMIT', 'Byte input exceeds maxBytes.');
+    // UTF-32 must not be mistaken for UTF-16LE, and is unsupported by TextDecoder.
+    if ((bytes[0] === 0xff && bytes[1] === 0xfe && bytes[2] === 0 && bytes[3] === 0) ||
+        (bytes[0] === 0 && bytes[1] === 0 && bytes[2] === 0xfe && bytes[3] === 0xff))
+        return fail('UNSUPPORTED_BOM', 'UTF-32 input is unsupported.');
+    const bom = bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf ? 'utf-8'
+        : bytes[0] === 0xff && bytes[1] === 0xfe ? 'utf-16le' : bytes[0] === 0xfe && bytes[1] === 0xff ? 'utf-16be' : null;
+    let decoder;
+    try {
+        decoder = new TextDecoder(options.encoding ?? bom ?? 'utf-8', { fatal: true });
+    }
+    catch {
+        return fail('UNSUPPORTED_ENCODING', 'Encoding label is unsupported by this runtime.', null, bom);
+    }
+    const encoding = decoder.encoding;
+    if (bom && encoding !== bom)
+        return fail('ENCODING_BOM_CONFLICT', 'Explicit encoding conflicts with the byte order mark.', encoding, bom);
+    try {
+        let text = decoder.decode(bytes);
+        if (encoding === 'windows-1252')
+            text = text.replace(/[\u0080-\u009f]/g, char => WINDOWS_1252_C1[char.charCodeAt(0) - 0x80]);
+        return { text, encoding, bom, diagnostics };
+    }
+    catch {
+        if (options.fatal !== false)
+            return fail('INVALID_ENCODING', 'Bytes are invalid for the selected encoding. Choose the correct encoding explicitly.', encoding, bom);
+        diagnostics.push({ code: 'DECODE_REPLACEMENT', severity: 'warning', message: 'Invalid byte sequences were replaced with U+FFFD at explicit caller request.' });
+        return { text: new TextDecoder(encoding).decode(bytes), encoding, bom, diagnostics };
+    }
+}

package/dist/detect.d.ts

@@ -0,0 +1,3 @@
+import type { Detection } from './types.js';
+/** Content-only heuristic, examining at most 64 Ki UTF-16 code units. No filename guessing. */
+export declare function detectFormat(text: string): Detection;

package/dist/detect.js

@@ -0,0 +1,38 @@
+/** Content-only heuristic, examining at most 64 Ki UTF-16 code units. No filename guessing. */
+export function detectFormat(text) {
+    if (typeof text !== 'string')
+        throw new TypeError('detectFormat expects a string.');
+    const sample = text.slice(0, 65_536).replace(/^\uFEFF/, '');
+    if (/^WEBVTT(?:[ \t\r\n]|$)/.test(sample))
+        return { format: 'vtt', confidence: 'high', candidates: ['vtt'] };
+    let offset = 0;
+    while (offset < sample.length) {
+        while (offset < sample.length && /\s/.test(sample[offset]))
+            offset++;
+        if (!sample.startsWith('<!--', offset))
+            break;
+        const end = sample.indexOf('-->', offset + 4);
+        if (end < 0)
+            break;
+        offset = end + 3;
+    }
+    const leading = sample.slice(offset);
+    if (/^<sami(?:\s|>)/i.test(leading))
+        return { format: 'sami', confidence: 'high', candidates: ['sami'] };
+    if (/^\[(?:Script Info|Events|V4\+? Styles)\]/i.test(leading)) {
+        const ssa = /(?:^|[\r\n])[ \t]*(?:ScriptType[ \t]*:[ \t]*v4\.00[ \t]*$|\[V4 Styles\])/im.test(sample);
+        const ass = /(?:^|[\r\n])[ \t]*(?:ScriptType[ \t]*:[ \t]*v4\.00\+|\[V4\+ Styles\])/im.test(sample);
+        if (ssa && ass)
+            return { format: null, confidence: 'ambiguous', candidates: ['ass', 'ssa'] };
+        return { format: ssa ? 'ssa' : 'ass', confidence: ass || ssa ? 'high' : 'low', candidates: [ssa ? 'ssa' : 'ass'] };
+    }
+    if (/(?:^|[\r\n])[ \t]*\d+:\d{2}:\d{2},\d{3}[ \t]+-->/.test(sample))
+        return { format: 'srt', confidence: 'high', candidates: ['srt'] };
+    if (/(?:^|[\r\n])[ \t]*\d+:\d{2}:\d{2},\d{3}[ \t]+->/.test(sample))
+        return { format: 'srt', confidence: 'low', candidates: ['srt'] };
+    if (/(?:^|[\r\n])[ \t]*(?:\d+:)?\d{2}:\d{2}\.\d{3}[ \t]+-->/.test(sample))
+        return { format: null, confidence: 'ambiguous', candidates: ['srt', 'vtt'] };
+    if (/<sync\b[^<>]*\bstart\s*=/i.test(sample))
+        return { format: 'sami', confidence: 'low', candidates: ['sami'] };
+    return { format: null, confidence: 'none', candidates: [] };
+}

package/dist/entities.d.ts

@@ -0,0 +1 @@
+export declare const HTML_ENTITIES: Readonly<Record<string, string>>;