@hypit/hypit 0.0.1 → 0.1.1

package/dist/public/author-kit.d.ts

@@ -0,0 +1,559 @@
+/** Opaque identity for one admitted byte resource. Equal bytes may have different identities. */
+type ResourceId = `res_${string}`;
+type RecordId = string;
+type LogicalOutputId = string;
+type NeedId = string;
+type StepId = string;
+type CommandId = string;
+type ModuleRef = {
+    readonly name: string;
+    readonly version: string;
+};
+/**
+ * A Type is its owning Module and its name, and nothing else is compared. Two Types whose values
+ * carry identical shapes are distinct, so one is refused where the other is declared — there is no
+ * structural fallback to fall back to.
+ */
+type TypeRef = {
+    readonly module: ModuleRef;
+    readonly name: string;
+};
+type ProducerRef = {
+    readonly module: ModuleRef;
+    readonly name: string;
+};
+type CapabilityRef = {
+    readonly module: ModuleRef;
+    readonly name: string;
+};
+declare function sameType(left: TypeRef, right: TypeRef): boolean;
+
+type CanonicalValue = null | boolean | number | string | readonly CanonicalValue[] | {
+    readonly [key: string]: CanonicalValue;
+};
+type BlobRef = {
+    readonly kind: "blob";
+    /** One admitted resource instance. Equal bytes admitted twice keep distinct identities. */
+    readonly resource: ResourceId;
+    readonly size: number;
+    readonly mediaType: string;
+};
+type StoredValue = {
+    readonly kind: "inline";
+    readonly value: CanonicalValue;
+} | BlobRef;
+type ValueSchema = {
+    readonly kind: "null";
+} | {
+    readonly kind: "boolean";
+} | {
+    readonly kind: "number";
+    readonly integer?: boolean;
+    readonly minimum?: number;
+    readonly maximum?: number;
+} | {
+    readonly kind: "string";
+    readonly enum?: readonly string[];
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    /** UI-neutral semantic format shared by authoring, validation and tools. */
+    readonly format?: "color";
+} | {
+    readonly kind: "literal";
+    readonly value: CanonicalValue;
+} | {
+    readonly kind: "array";
+    readonly items: ValueSchema;
+    readonly minItems?: number;
+    readonly maxItems?: number;
+} | {
+    readonly kind: "object";
+    readonly fields: Readonly<Record<string, ObjectFieldSchema>>;
+    readonly allowUnknown?: boolean;
+} | {
+    readonly kind: "oneOf";
+    readonly variants: readonly ValueSchema[];
+} | {
+    readonly kind: "blob";
+    readonly mediaTypes?: readonly string[];
+    readonly maxBytes?: number;
+};
+type ObjectFieldSchema = {
+    readonly schema: ValueSchema;
+    readonly optional?: boolean;
+};
+
+declare function canonicalize(value: unknown): CanonicalValue;
+declare function isResourceId(value: string): value is ResourceId;
+
+type ModuleDependency = {
+    readonly module: ModuleRef;
+};
+type TypeDeclaration = {
+    readonly name: string;
+};
+type PortDeclaration = {
+    readonly name: string;
+    readonly type: TypeRef;
+};
+type NeedPortDeclaration = {
+    readonly name: string;
+    readonly capability: CapabilityRef;
+    readonly returns: TypeRef;
+};
+type CapabilityDeclaration = {
+    readonly name: string;
+    readonly returns: TypeRef;
+};
+type ProducerDeclaration = {
+    readonly name: string;
+    readonly inputs: readonly PortDeclaration[];
+    readonly outputs: readonly PortDeclaration[];
+    readonly needs: readonly NeedPortDeclaration[];
+};
+type ModuleManifest = {
+    readonly format: "hypit.module@1";
+    readonly name: string;
+    readonly version: string;
+    readonly dependencies: readonly ModuleDependency[];
+    readonly types: readonly TypeDeclaration[];
+    readonly capabilities: readonly CapabilityDeclaration[];
+    readonly producers: readonly ProducerDeclaration[];
+};
+type ResolvedModule = {
+    readonly manifest: ModuleManifest;
+};
+type ResolvedModuleClosure = {
+    readonly format: "hypit.closure@1";
+    readonly modules: readonly ResolvedModule[];
+};
+
+type SourceRange = {
+    readonly start: number;
+    readonly end: number;
+};
+/** One typed value in the graph; semantic validation happens at the Host admission boundary. */
+type TypedRecord = {
+    readonly id: RecordId;
+    readonly type: TypeRef;
+    readonly value: StoredValue;
+};
+type Need = {
+    readonly id: NeedId;
+    readonly capability: CapabilityRef;
+    readonly returns: TypeRef;
+    readonly constraints: CanonicalValue;
+    readonly result: RecordId;
+};
+type NeedBinding = {
+    readonly id: NeedId;
+    readonly result: RecordId;
+};
+type BuildTarget = {
+    readonly output: LogicalOutputId;
+};
+type BuildOutputBinding = {
+    readonly output: LogicalOutputId;
+    readonly record: RecordId;
+    readonly type: TypeRef;
+};
+type ProducerStep = {
+    readonly id: StepId;
+    readonly producer: ProducerRef;
+    readonly inputs: Readonly<Record<string, RecordId>>;
+    readonly outputs: Readonly<Record<string, RecordId>>;
+    readonly needs: Readonly<Record<string, NeedBinding>>;
+};
+type BuildGoal = {
+    readonly record: RecordId;
+    readonly type: TypeRef;
+};
+type BuildPlan = {
+    readonly format: "hypit.plan@1";
+    readonly steps: readonly ProducerStep[];
+    readonly goals: readonly BuildGoal[];
+    /** Every Logical Output reached by the selected execution, independent of how it was supplied. */
+    readonly outputBindings: readonly BuildOutputBinding[];
+};
+type LinkedProgram = {
+    readonly closure: ResolvedModuleClosure;
+    readonly records: readonly TypedRecord[];
+};
+type StepState = {
+    readonly id: StepId;
+    readonly status: "pending" | "complete";
+};
+type InvokeProducerCommand = {
+    readonly kind: "invoke-producer";
+    readonly id: CommandId;
+    readonly step: StepId;
+    readonly producer: ProducerRef;
+    readonly inputs: Readonly<Record<string, RecordId>>;
+};
+type FulfillNeedCommand = {
+    readonly kind: "fulfill-need";
+    readonly id: CommandId;
+    readonly need: Need;
+};
+type CoreCommand = InvokeProducerCommand | FulfillNeedCommand;
+type BuildDiagnostic = {
+    readonly code: string;
+    readonly message: string;
+    readonly subject?: string;
+};
+/** Materialized read/execution view. Durable Stores persist Definition + Facts, never this object. */
+type BuildState = {
+    readonly format: "hypit.build@1";
+    readonly program: LinkedProgram;
+    readonly plan: BuildPlan;
+    readonly targets: readonly BuildTarget[];
+    readonly status: "active" | "complete" | "failed";
+    readonly records: readonly TypedRecord[];
+    readonly steps: readonly StepState[];
+    readonly needs: readonly Need[];
+    readonly outstanding: readonly CoreCommand[];
+    readonly diagnostics: readonly BuildDiagnostic[];
+};
+
+type Awaitable$1<T> = T | Promise<T>;
+type TypeValidatorContext = {
+    readonly type: TypeRef;
+    readonly value: StoredValue;
+};
+type TypeValidatorHandler = (context: TypeValidatorContext) => void | Promise<void>;
+type ProducerHandlerResult = {
+    readonly outputs: Readonly<Record<string, StoredValue>>;
+    readonly needs: Readonly<Record<string, CanonicalValue>>;
+};
+/**
+ * Pure compute context. Artifact bytes, credentials, network and stores are deliberately absent;
+ * those effects must cross an explicit Need into a Provider.
+ */
+type ProducerHandlerContext = {
+    readonly command: InvokeProducerCommand;
+    readonly producer: ProducerRef;
+    readonly inputs: Readonly<Record<string, TypedRecord>>;
+};
+type ProducerHandler = (context: ProducerHandlerContext) => Awaitable$1<ProducerHandlerResult>;
+/** Enumerable deterministic Producer handler owned by its package. */
+type ProducerFacet = {
+    readonly producer: ProducerRef;
+    readonly handler: ProducerHandler;
+};
+/** One input whose value will exist only after an upstream Build step has run. */
+type PlannedNeedInput = {
+    readonly input: string;
+    readonly record: string;
+    readonly sourceStep?: string;
+    /** Capability-owned semantic role when the value represents media, such as image or audio. */
+    readonly role?: string;
+};
+/**
+ * The complete support-relevant request known before external work starts. Values produced later
+ * are represented by input slots; their eventual StoredValues are execution bindings, not missing
+ * author intent. A slot may be a Resource or a structured value.
+ */
+type PlannedNeedSpecification = {
+    readonly constraints: CanonicalValue;
+    readonly pendingInputs: readonly PlannedNeedInput[];
+};
+/** Package-owned, presentation-neutral reading of one request. */
+type PlannedNeedPresentation = {
+    readonly fields: Readonly<Record<string, readonly CanonicalValue[]>>;
+    readonly references: Readonly<Record<string, number>>;
+};
+type PlannedNeedFacet = {
+    readonly producer: ProducerRef;
+    readonly port: string;
+    readonly capability: CapabilityRef;
+    plan(input: {
+        readonly state: BuildState;
+        readonly step: string;
+        readonly port: string;
+    }): PlannedNeedSpecification | undefined;
+    present?(specification: PlannedNeedSpecification): PlannedNeedPresentation;
+};
+/** Package-owned semantic validator. */
+type TypeValidatorFacet = {
+    readonly type: TypeRef;
+    readonly handler: TypeValidatorHandler;
+};
+/** Trusted deterministic implementation package; it selects no Provider or Runtime infrastructure. */
+type ComponentPackage = {
+    readonly producers?: readonly ProducerFacet[];
+    readonly validators?: readonly TypeValidatorFacet[];
+    /** Planning knowledge owned by the package that declares the external request. */
+    readonly plannedNeeds?: readonly PlannedNeedFacet[];
+};
+
+type FragmentInputRef = {
+    readonly kind: "fragment-input";
+    readonly name: string;
+};
+type FragmentOperationRef = {
+    readonly kind: "fragment-operation";
+    readonly operation: string;
+};
+type FragmentValueRef = FragmentInputRef | FragmentOperationRef;
+type FragmentOperationResult = {
+    readonly kind: "output";
+    readonly name: string;
+} | {
+    readonly kind: "need";
+    readonly name: string;
+};
+type FragmentOperation = {
+    readonly id: string;
+    readonly producer: ProducerRef;
+    readonly inputs: Readonly<Record<string, FragmentValueRef>>;
+    readonly result: FragmentOperationResult;
+};
+type FragmentExport = {
+    readonly name: string;
+    readonly type: TypeRef;
+    readonly root: FragmentOperationRef;
+};
+type GraphFragment = {
+    readonly format: "hypit.fragment@1";
+    readonly id: string;
+    readonly inputs: readonly {
+        readonly name: string;
+        readonly type: TypeRef;
+    }[];
+    readonly operations: readonly FragmentOperation[];
+    readonly exports: readonly FragmentExport[];
+};
+declare function sealGraphFragment(fragment: Omit<GraphFragment, "format" | "id">): GraphFragment;
+
+/** A reference to an authored fact that already exists in the Linked Program. */
+type AuthorRecordRef = {
+    readonly kind: "record";
+    readonly id: string;
+};
+/** A symbolic reference to one public export of another component instance. */
+type AuthorComponentOutputRef = {
+    readonly kind: "component-output";
+    readonly component: string;
+    readonly output: string;
+};
+type AuthorValueRef = AuthorRecordRef | AuthorComponentOutputRef;
+/**
+ * One author-visible component call. `outputs` binds every public Fragment export to a Logical Output.
+ */
+type AuthorComponent = {
+    readonly id: string;
+    readonly fragment: string;
+    readonly inputs: Readonly<Record<string, AuthorValueRef>>;
+    readonly outputs: Readonly<Record<string, string>>;
+};
+
+type SourceAssetRequest = {
+    readonly from: string;
+    readonly mediaType: string;
+    /** Package-owned bytes admitted by the compiler before a Workspace is consulted. */
+    readonly bytes?: Uint8Array;
+    readonly range?: SourceRange;
+};
+type ResolvedSourceAsset = {
+    readonly artifact: BlobRef;
+};
+
+/** A semantic source dependency requested by a Frontend or package-owned Surface. */
+type AuthorSourceAssetRequest = SourceAssetRequest;
+type ResolvedAuthorSourceAsset = ResolvedSourceAsset;
+/**
+ * One author-visible identity whose uniqueness is part of a domain's public
+ * contract. The Frontend only carries the declaration; the owning Surface
+ * chooses the Type namespace and the Source closure enforces it generically.
+ */
+type AuthorSourceIdentity = {
+    readonly namespace: TypeRef;
+    readonly id: string;
+};
+type Awaitable<T> = T | Promise<T>;
+
+/** One package contribution understood only by the Host that owns its ABI. */
+type HostFacet = {
+    readonly abi: string;
+    readonly offers?: readonly string[];
+    readonly implementation: unknown;
+};
+
+type MarkupReference = {
+    readonly kind: "reference";
+    readonly path: string;
+};
+type MarkupAttributeValue = string | MarkupReference;
+type StructuredText = {
+    readonly kind: "text";
+    readonly value: string;
+    readonly range: SourceRange;
+};
+type StructuredElement = {
+    readonly kind: "element";
+    readonly name: string;
+    readonly attributes: Readonly<Record<string, MarkupAttributeValue>>;
+    /** Exact ranges of literal/reference values in the opening tag. */
+    readonly attributeValueRanges?: Readonly<Record<string, SourceRange>>;
+    readonly children: readonly StructuredNode[];
+    readonly range: SourceRange;
+};
+type StructuredNode = StructuredText | StructuredElement;
+type SurfaceRecordDraft = {
+    readonly id: string;
+    readonly type: TypeRef;
+    readonly value: StoredValue;
+    readonly range: SourceRange;
+};
+/** Source-local diagnostics are removed before the component enters semantic elaboration. */
+type SurfaceComponentDraft = AuthorComponent & {
+    readonly range: SourceRange;
+};
+type SurfaceDecodeOutput = {
+    readonly records: readonly SurfaceRecordDraft[];
+    readonly components: readonly SurfaceComponentDraft[];
+    readonly fragments: readonly GraphFragment[];
+    /** Domain-owned public identities that must be unique in the Source closure. */
+    readonly identities?: readonly AuthorSourceIdentity[];
+    /**
+     * Public source bindings contributed by this Surface invocation. Omit to
+     * publish every generated binding; use an explicit list to keep plumbing
+     * addressable inside the source without exposing it from the source.
+     */
+    readonly exports?: readonly string[];
+};
+type RawSurfaceInput = {
+    readonly sourceName: string;
+    readonly source: string;
+    readonly tag: string;
+    readonly openingStart: number;
+    readonly contentStart: number;
+    readonly attributes: Readonly<Record<string, MarkupAttributeValue>>;
+    readonly resolveAsset: (request: AuthorSourceAssetRequest) => Awaitable<ResolvedAuthorSourceAsset>;
+};
+type RawSurfaceOutput = SurfaceDecodeOutput & {
+    readonly nextOffset: number;
+};
+type StructuredSurfaceInput = {
+    readonly sourceName: string;
+    readonly element: StructuredElement;
+    /**
+     * Resolve an explicitly written author reference. Imported record values are
+     * available because their source has already been compiled and admitted.
+     * A component output has a ref and Type but no compile-time Record value.
+     */
+    readonly resolveReference: (path: string) => SurfaceResolvedReference | undefined;
+    readonly resolveAsset: (request: AuthorSourceAssetRequest) => Awaitable<ResolvedAuthorSourceAsset>;
+};
+type SurfaceResolvedReference = {
+    readonly path: string;
+    readonly ref: AuthorValueRef;
+    readonly type: TypeRef;
+    readonly record?: TypedRecord;
+};
+type RawSurfaceHandler = (input: RawSurfaceInput) => Awaitable<RawSurfaceOutput>;
+type StructuredSurfaceHandler = (input: StructuredSurfaceInput) => Awaitable<SurfaceDecodeOutput>;
+type SurfaceAttributeKind = "identifier" | "literal" | "reference" | "expression";
+type SurfaceRecipePropertyVocabulary = {
+    readonly name: string;
+    readonly required: boolean;
+    readonly summary: string;
+    /** The author value's public structure; it contains no editor presentation. */
+    readonly schema?: ValueSchema;
+    readonly values?: readonly string[];
+    /** Decoded author default; when a schema is present this value conforms to that public structure. */
+    readonly fallback?: CanonicalValue;
+};
+type SurfaceAttributeVocabulary = {
+    readonly name: string;
+    readonly kind: SurfaceAttributeKind;
+    readonly required: boolean;
+    readonly summary: string;
+    readonly values?: readonly string[];
+    readonly accepts?: readonly TypeRef[];
+    readonly recipe?: readonly SurfaceRecipePropertyVocabulary[];
+};
+type SurfaceChildVocabulary = {
+    readonly tag: string;
+    readonly cardinality: "one" | "optional" | "many";
+    readonly summary: string;
+    readonly attributes?: readonly SurfaceAttributeVocabulary[];
+    /** Elements written inside this child, declared to the same depth the Surface accepts them. */
+    readonly children?: readonly SurfaceChildVocabulary[];
+    readonly text?: string;
+};
+type SurfacePortVocabulary = {
+    readonly name: string;
+    readonly type: TypeRef;
+    readonly summary: string;
+};
+type SurfacePreview = {
+    readonly mediaType: string;
+    readonly path: string;
+    readonly open: () => Promise<Uint8Array>;
+};
+type SurfaceVocabulary = {
+    readonly summary: string;
+    readonly appearance?: string;
+    readonly preview?: SurfacePreview;
+    readonly attributes: readonly SurfaceAttributeVocabulary[];
+    readonly children?: readonly SurfaceChildVocabulary[];
+    readonly ports?: readonly SurfacePortVocabulary[];
+    readonly text?: string;
+    readonly example: string;
+    readonly notes?: readonly string[];
+};
+type MarkupSurfaceDeclarationBase = {
+    readonly name: string;
+    readonly tag: string;
+    readonly outputs: readonly TypeRef[];
+    readonly vocabulary?: SurfaceVocabulary;
+};
+type RawSurfaceDeclaration = MarkupSurfaceDeclarationBase & {
+    readonly mode: "raw";
+};
+type StructuredSurfaceDeclaration = MarkupSurfaceDeclarationBase & {
+    readonly mode: "structured";
+};
+
+declare function assertAttributes(element: StructuredElement, allowed: readonly string[], required?: readonly string[]): void;
+declare function assertExactAttributes(element: StructuredElement, names: readonly string[]): void;
+declare function assertEmptyElement(element: StructuredElement): void;
+declare function localName(name: string): string;
+declare function textAttribute(element: StructuredElement, name: string, fallback?: string): string;
+declare function optionalTextAttribute(element: StructuredElement, name: string): string | undefined;
+
+type RawMarkupSurfaceHostFacetOptions = {
+    readonly module: ModuleRef;
+    readonly surface: string;
+    readonly tag: string;
+    readonly outputs: readonly TypeRef[];
+    readonly vocabulary?: SurfaceVocabulary;
+    readonly mode: "raw";
+    readonly handler: RawSurfaceHandler;
+} | {
+    readonly module: ModuleRef;
+    readonly declaration: RawSurfaceDeclaration;
+    readonly handler: RawSurfaceHandler;
+};
+type StructuredMarkupSurfaceHostFacetOptions = {
+    readonly module: ModuleRef;
+    readonly surface: string;
+    readonly tag: string;
+    readonly outputs: readonly TypeRef[];
+    readonly vocabulary?: SurfaceVocabulary;
+    readonly mode: "structured";
+    readonly handler: StructuredSurfaceHandler;
+} | {
+    readonly module: ModuleRef;
+    readonly declaration: StructuredSurfaceDeclaration;
+    readonly handler: StructuredSurfaceHandler;
+};
+
+type MarkupSurfaceHostFacetOptions = RawMarkupSurfaceHostFacetOptions | StructuredMarkupSurfaceHostFacetOptions;
+/** Package-owned Markup Surface declaration carried through the syntax-neutral package loader. */
+declare function createMarkupSurfaceHostFacet(options: RawMarkupSurfaceHostFacetOptions): HostFacet;
+declare function createMarkupSurfaceHostFacet(options: StructuredMarkupSurfaceHostFacetOptions): HostFacet;
+
+export { assertAttributes, assertEmptyElement, assertExactAttributes, canonicalize, createMarkupSurfaceHostFacet, isResourceId, localName, optionalTextAttribute, sameType, sealGraphFragment, textAttribute };
+export type { BlobRef, CanonicalValue, ComponentPackage, FragmentOperation, GraphFragment, MarkupSurfaceHostFacetOptions, ModuleManifest, ModuleRef, ProducerFacet, ProducerHandler, ProducerHandlerContext, ProducerHandlerResult, ProducerRef, StoredValue, StructuredElement, StructuredSurfaceHandler, SurfaceComponentDraft, SurfaceRecordDraft, SurfaceResolvedReference, TypeRef, TypeValidatorFacet, TypeValidatorHandler, TypedRecord, ValueSchema };

package/dist/public/browser-capture.d.ts

@@ -0,0 +1,56 @@
+import { LaunchOptions, Browser, Page, ScreenshotOptions, RecordOptions } from 'puppeteer-core';
+
+declare function captureBrowserExecutablePath(): Promise<string>;
+/** Explicit setup, using Puppeteer's cache configuration and upstream browser installer. */
+declare function installCaptureBrowser(): Promise<string>;
+
+type CaptureOptions = {
+    /** Ordinary Puppeteer launch options, including channel, executablePath and defaultViewport. */
+    readonly launch?: LaunchOptions;
+    /** Page operation and navigation timeout; Puppeteer's default applies when omitted. */
+    readonly timeoutMs?: number;
+    /** Used to read the actual dimensions and duration after a recording finishes. */
+    readonly ffprobePath?: string;
+};
+type CaptureOutput = {
+    readonly kind: "image" | "video";
+    readonly path: string;
+    readonly url: string;
+    readonly width: number;
+    readonly height: number;
+    readonly format: string;
+    readonly duration?: number;
+    readonly frameRate?: number;
+    readonly hasAudio?: boolean;
+};
+type ScreenshotCaptureOptions = Omit<ScreenshotOptions, "path" | "encoding"> & {
+    readonly path: string;
+    readonly selector?: string;
+};
+type RecordingCaptureOptions = Omit<RecordOptions, "path" | "overwrite"> & {
+    readonly path: string;
+};
+type CaptureRecording = {
+    stop(): Promise<CaptureOutput>;
+};
+type CaptureSession = {
+    readonly browser: Browser;
+    readonly page: Page;
+    /** Capture the default page, or a page created by the script in this browser. */
+    screenshot(options: ScreenshotCaptureOptions, page?: Page): Promise<CaptureOutput>;
+    /** Record page changes through Chrome's native recorder; audio is opt-in. */
+    record(options: RecordingCaptureOptions, page?: Page): Promise<CaptureRecording>;
+};
+type CaptureScriptContext = CaptureSession & {
+    readonly args: readonly string[];
+    log(message: string): void;
+};
+type CaptureScript = (context: CaptureScriptContext) => Promise<void>;
+/**
+ * One browser for an authored capture task. The callback uses ordinary Puppeteer objects;
+ * no website interpretation, Runtime, Build, or Source graph participates here.
+ */
+declare function withCapture(options: CaptureOptions, task: (session: CaptureSession) => Promise<void>, onOutput?: (output: CaptureOutput) => void): Promise<readonly CaptureOutput[]>;
+
+export { captureBrowserExecutablePath, installCaptureBrowser, withCapture };
+export type { CaptureOptions, CaptureOutput, CaptureRecording, CaptureScript, CaptureScriptContext, CaptureSession, RecordingCaptureOptions, ScreenshotCaptureOptions };