@ue-shed/game-text 0.1.0

package/ADOPTING.md

@@ -0,0 +1,59 @@
+# Adopt Game Text into an existing host
+
+This guide is for the coding agent integrating the headless Game Text Module into an established
+trusted host. Read [`adoption.manifest.json`](adoption.manifest.json) first. Do not inspect or copy
+Workbench unless a named verification failure leaves the public package contract insufficient.
+
+## Fast path
+
+1. Inspect the target's package manifest, Node version, Effect version, selected-project model, and
+   saved-asset reader configuration.
+2. Install the exact `@ue-shed/game-text` version. Reuse a compatible existing
+   `@ue-shed/unreal-assets` and `@ue-shed/uasset` installation when present.
+3. In the target's trusted Node process, compose one scoped `AssetReader` layer and
+   `TextCorpusServiceLive`. Do not create a sidecar server or a reader layer per asset.
+4. Adapt the host's explicit project root or existing project index to `scan` or
+   `scanFromProjectIndex`.
+5. Keep the complete corpus and `textCorpusQuery` model in the trusted host. Add schema-validated
+   host operations for progress, summary, bounded search, and bounded focus using the target's
+   existing transport conventions.
+6. Add an adopter-owned view only if the host needs one. This bundle contains no maintained UI and
+   requires no Solid, StyleX, Electron, or Workbench package.
+7. Prove the acceptance journey below and record the exact package versions, reader provider, target
+   files, project input, and verification commands in the host repository.
+
+## Ownership
+
+- UE Shed owns the installed package and its schemas.
+- The adopting host owns project selection, runtime composition, transport Adapter, caching policy,
+  route, presentation, and navigation.
+- Browser code receives only bounded schema-validated results. It must not receive the corpus,
+  filesystem paths beyond returned evidence, process authority, or the reader executable.
+- Do not import `apps/workbench`, `extensions/game-text`, or Workbench transport modules.
+- Do not add `@ue-shed/uasset` as a hidden dependency of Game Text. The host deliberately selects
+  the default launcher or an explicit compatible executable.
+
+## Required and optional capabilities
+
+The core audit requires saved project packages and a configured reader. It does not require a
+running editor, Perforce, `UEShedCore`, or any other UE Shed Unreal plugin.
+
+“Locate in Unreal” is an optional host enhancement. Keep it outside the audit Module and expose an
+honest unavailable state when the host has no compatible editor-selection capability.
+
+## Acceptance journey
+
+The integration is complete only when the target host can:
+
+1. Select an explicit project root without relying on ambient UI state.
+2. Scan its saved packages with visible progress and cancellation owned by the host.
+3. Return a summary that includes scan coverage and diagnostics.
+4. Search with the public maximum page size enforced.
+5. Focus a selected text-unit ID and return bounded occurrence evidence.
+6. Run with Unreal offline and report unsupported or partial evidence without claiming complete
+   project coverage.
+7. Build and run from the target's packaged application, resolving the configured reader there.
+
+UE Shed's source release gate runs `pnpm test:release:packages`. The adopter must add a target-owned
+command that proves the same scan → search → focus journey through its real host transport. A direct
+package call is useful diagnosis but is not evidence that the host Adapter works.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UE Shed 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

@@ -0,0 +1,47 @@
+# `@ue-shed/game-text`
+
+Headless saved-package corpus discovery and search for player-facing Unreal Engine text. The
+package keeps Unreal namespace/key identity distinct from occurrence identity, reports scan
+coverage, and returns bounded search and focus results. Saved packages are evidence only; this
+package does not mutate assets.
+
+## Install
+
+Pin the package and the host's Effect runtime exactly:
+
+```sh
+npm install --save-exact @ue-shed/game-text effect@4.0.0-beta.98
+```
+
+`@ue-shed/unreal-assets` is a normal package dependency. It remains a separate artifact and is not
+bundled into Game Text. A saved-asset reader executable is also required at runtime, but it is not a
+JavaScript dependency of this package. Install the default launcher separately:
+
+```sh
+npm install --save-exact @ue-shed/uasset
+```
+
+Alternatively, configure `assetReaderLayer({ executable })` with another compatible `uasset-io`
+producer. The reader library never downloads an executable or falls back to a source checkout.
+
+## Host usage
+
+Compose `TextCorpusServiceLive` with one scoped `AssetReader` layer in the trusted Node host. Keep
+the resulting corpus and `textCorpusQuery(corpus)` model in that host, and send only bounded summary,
+search, and focus results over the host's validated transport.
+
+Use `scanFromProjectIndex` when the host already maintains a saved-project header index. Otherwise,
+`scan` performs its own bounded project scan. Both paths preserve coverage and typed recovery
+guidance.
+
+The `@ue-shed/game-text/browser` entry point contains only schemas and pure query helpers. It does
+not expose filesystem, process, Electron, Perforce, or Unreal authority.
+
+See [ADOPTING.md](ADOPTING.md) and [adoption.manifest.json](adoption.manifest.json) when integrating
+Game Text into an established trusted host.
+
+## Capabilities
+
+- Required: a project root containing saved packages and a configured saved-asset reader.
+- Optional: a separate host capability may locate a selected occurrence in Unreal.
+- Not required: Workbench, Perforce, a running editor, or any UE Shed Unreal plugin.

package/adoption.manifest.json

@@ -0,0 +1,68 @@
+{
+	"schemaVersion": 1,
+	"feature": "game-text",
+	"mode": "existing-host-package",
+	"description": "Headless saved-package Game Text corpus, coverage, search, and focus",
+	"release": {
+		"package": "@ue-shed/game-text",
+		"versionSource": "package.json",
+		"exactVersionRequired": true,
+		"nativeBinaryBundled": false,
+		"uiBundled": false
+	},
+	"entrypoints": {
+		"host": "@ue-shed/game-text",
+		"browser": "@ue-shed/game-text/browser"
+	},
+	"packageGraph": {
+		"dependencies": {
+			"@ue-shed/unreal-assets": "package.json#dependencies"
+		},
+		"peerDependencies": {
+			"effect": "4.0.0-beta.98"
+		},
+		"runtimeProviders": [
+			{
+				"capability": "saved-asset-reader",
+				"defaultPackage": "@ue-shed/uasset",
+				"versionPolicy": "save-exact compatible release",
+				"alternative": "Explicit compatible executable supplied to assetReaderLayer"
+			}
+		]
+	},
+	"hostIntegration": {
+		"ownership": "consumer",
+		"requiredSeams": [
+			"explicit-project-root-or-project-index",
+			"process-scoped-asset-reader",
+			"trusted-host-text-corpus-runtime",
+			"schema-validated-transport-adapter",
+			"bounded-search-and-focus-client"
+		],
+		"forbiddenImports": [
+			"apps/workbench",
+			"extensions/game-text",
+			"@ue-shed/workbench",
+			"@ue-shed/extension-game-text"
+		],
+		"browserAuthoritiesForbidden": [
+			"filesystem",
+			"process",
+			"electron",
+			"unreal",
+			"native-reader"
+		]
+	},
+	"capabilities": {
+		"required": ["saved-project", "saved-asset-reader"],
+		"optional": ["locate-occurrence-in-unreal"],
+		"notRequired": ["perforce", "running-unreal-editor", "ue-shed-unreal-plugin"]
+	},
+	"conformance": {
+		"sourceCommand": "pnpm test:release:packages",
+		"journey": ["scan", "coverage", "search", "focus", "offline-unreal"],
+		"targetMustVerifyPackagedRuntime": true,
+		"targetMustUseRealHostTransport": true,
+		"targetMustRecordAdoptionReceipt": true
+	}
+}

package/dist/browser.d.ts

@@ -0,0 +1,7 @@
+export * from "./quality-schema.js";
+export * from "./quality.js";
+export * from "./quality-query.js";
+export * from "./schema.js";
+export * from "./query.js";
+export * from "./search.js";
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC"}

package/dist/browser.js

@@ -0,0 +1,7 @@
+export * from "./quality-schema.js";
+export * from "./quality.js";
+export * from "./quality-query.js";
+export * from "./schema.js";
+export * from "./query.js";
+export * from "./search.js";
+//# sourceMappingURL=browser.js.map

package/dist/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC"}

package/dist/corpus.d.ts

@@ -0,0 +1,70 @@
+import { AssetReader, type SavedAssetInspection, type SavedAssetScan } from "@ue-shed/unreal-assets";
+import { Context, Effect, Layer, Schema } from "effect";
+import { type TextCorpus, type TextOccurrence } from "./schema.js";
+interface ExtractionProgress {
+    readonly phase: "idle" | "scanning" | "ready" | "failed";
+    readonly processedAssets: number;
+    readonly totalAssets: number;
+}
+declare const TextCorpusScanError_base: Schema.Class<TextCorpusScanError, Schema.TaggedStruct<"TextCorpusScanError", {
+    readonly code: Schema.Literals<readonly ["invalid_project", "scan_limit_exceeded"]>;
+    readonly message: Schema.String;
+    readonly recovery: Schema.String;
+    readonly retrySafe: Schema.Boolean;
+}>, import("effect/Cause").YieldableError>;
+export declare class TextCorpusScanError extends TextCorpusScanError_base {
+}
+export declare const TextCorpusScanOptions: Schema.Struct<{
+    readonly concurrency: Schema.optional<Schema.Int>;
+    readonly maximumAssets: Schema.optional<Schema.Int>;
+    readonly projectRoot: Schema.String;
+}>;
+export type TextCorpusScanOptions = Schema.Schema.Type<typeof TextCorpusScanOptions>;
+export declare const STRING_TABLE_CLASS = "/Script/Engine.StringTable";
+/**
+ * Tagged property serialization writes each property's type as a name-table entry, so a package
+ * holding any `FText` names `TextProperty` in its header.
+ */
+export declare const TEXT_PROPERTY_NAME = "TextProperty";
+/** @deprecated Prefer TextCorpusScanOptions */
+export type ScanTextCorpusOptions = TextCorpusScanOptions;
+export type TextPackageOutcome = {
+    readonly status: "inspected";
+    readonly packageFile: string;
+    readonly inspection: SavedAssetInspection;
+} | {
+    readonly status: "failed";
+    readonly packageFile: string;
+    readonly message: string;
+};
+export declare function textOccurrencesFromInspection(options: {
+    readonly inspection: SavedAssetInspection;
+    readonly packageFile: string;
+}): readonly TextOccurrence[];
+/** Paths whose existing header-index projection proves they may contribute game text. */
+export declare function textPackagePathsFromProjectIndex(index: SavedAssetScan): readonly string[];
+/**
+ * Package counts from a batched scan. A filtered scan never reports packages the reader ruled out
+ * from their headers, so discovered and inspected cannot be derived from `outcomes` alone.
+ */
+export interface TextPackageCounts {
+    readonly discoveredPackages: number;
+    readonly inspectedPackages: number;
+}
+export declare function buildTextCorpus(outcomes: readonly TextPackageOutcome[], counts?: TextPackageCounts): TextCorpus;
+export interface TextCorpusServiceShape {
+    readonly progress: () => Effect.Effect<ExtractionProgress>;
+    readonly scan: (options: TextCorpusScanOptions) => Effect.Effect<TextCorpus, TextCorpusScanError>;
+    readonly scanFromProjectIndex: (index: SavedAssetScan, options: TextCorpusScanOptions) => Effect.Effect<TextCorpus, TextCorpusScanError>;
+}
+declare const TextCorpusService_base: Context.ServiceClass<TextCorpusService, "@ue-shed/game-text/TextCorpus", TextCorpusServiceShape>;
+/** Canonical TextCorpus domain service (plan name: TextCorpus.Service). */
+export declare class TextCorpusService extends TextCorpusService_base {
+}
+export declare const TextCorpusServiceLive: Layer.Layer<TextCorpusService, never, AssetReader>;
+export type TextCorpusServiceTestShape = Omit<TextCorpusServiceShape, "progress" | "scanFromProjectIndex"> & Partial<Pick<TextCorpusServiceShape, "progress" | "scanFromProjectIndex">>;
+export declare function makeTextCorpusServiceTestLayer(service: TextCorpusServiceTestShape): Layer.Layer<TextCorpusService>;
+/** Compatibility accessor until Plans 012–014 compose TextCorpusService layers directly. */
+export declare function scanTextCorpus(options: TextCorpusScanOptions): Effect.Effect<TextCorpus, TextCorpusScanError, AssetReader>;
+export {};
+//# sourceMappingURL=corpus.d.ts.map

package/dist/corpus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"corpus.d.ts","sourceRoot":"","sources":["../src/corpus.ts"],"names":[],"mappings":"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"}