Embedding

Embedding

The browser application is exported from @pkistudio/asn1instancebuilder/app as initAsn1InstanceBuilder.

import { initAsn1InstanceBuilder } from '@pkistudio/asn1instancebuilder/app';
import '@pkistudio/asn1instancebuilder/styles.css';

const app = initAsn1InstanceBuilder({
  mount: '#app'
});

await app.build(false);

Mount Target

mount can be a selector or host element. The application fills the available browser viewport and manages its own Definition pane, Instance Input pane, Diagnostics pane, splitters, API Log, and viewer-window routing.

Initial Schema and Input

Pass an initial Schema Model and instance input when the host already owns the data:

import { initAsn1InstanceBuilder, type Asn1InstanceBuilderAppOptions } from '@pkistudio/asn1instancebuilder/app';

const options: Asn1InstanceBuilderAppOptions = {
  mount: '#app',
  schema,
  input
};

const app = initAsn1InstanceBuilder(options);

Hosts can also call loadSchema(schema), loadInput(input), and loadBundle(bundle, entryIdOrTypeName?) on the returned app instance.

Loading Definition Bundles

Definition Bundles let a host load schema data, named entries, sample or default Instance JSON, and optional UI Profile metadata through one app-facing object.

import { initAsn1InstanceBuilder, type DefinitionBundle } from '@pkistudio/asn1instancebuilder/app';
import '@pkistudio/asn1instancebuilder/styles.css';

const app = initAsn1InstanceBuilder({ mount: '#app' });

const rawAsn1Bundle: DefinitionBundle = {
  id: 'pkistudio.example.person',
  version: '1.0.0',
  label: 'Person Example',
  schema: {
    format: 'asn1',
    sourceName: 'person.asn1',
    source: `Example DEFINITIONS ::= BEGIN

Person ::= SEQUENCE {
  name UTF8String,
  age INTEGER OPTIONAL,
  email IA5String OPTIONAL
}

END`
  },
  entries: [{
    id: 'person',
    typeName: 'Person',
    sampleInput: { name: 'Alice', age: 42, email: 'alice@example.test' }
  }]
};

app.loadBundle(rawAsn1Bundle, 'person');

Bundles can also carry a parsed Schema Model instead of raw ASN.1 text:

const schemaModelBundle: DefinitionBundle = {
  id: 'pkistudio.example.person.schema-model',
  version: '1.0.0',
  label: 'Person Schema Model Example',
  schema: {
    format: 'schema-model',
    schema: {
      name: 'Example',
      tagDefault: 'explicit',
      types: [{
        name: 'Person',
        type: {
          kind: 'sequence',
          fields: [{ name: 'name', type: { kind: 'utf8String' } }]
        }
      }]
    }
  },
  entries: [{
    typeName: 'Person',
    defaultInput: { name: 'Alice' },
    uiProfile: {
      id: 'person-profile',
      typeName: 'Person',
      fields: { name: { label: 'Full name', placeholder: 'Alice' } }
    }
  }]
};

app.loadBundle(schemaModelBundle);

The built-in Load -> NamedObjects examples are also exported as reusable Definition Bundles:

import { namedObjectDefinitionBundles } from '@pkistudio/asn1instancebuilder/app';

const certificateBundle = namedObjectDefinitionBundles.find((bundle) => bundle.id === 'certificate');
if (certificateBundle) app.loadBundle(certificateBundle, 'certificate');

The browser app can also load external .definition-bundle.json or .bundle.json files from Load -> Definition Bundle. This uses the same loadBundle() behavior while keeping raw ASN.1/Schema file loading separate from portable bundle loading.

The browser app can export the active workspace from Save -> Definition Bundle. The saved file includes the current definition source, selected type, current JSON sample input, and active UI Profile metadata when available. When the workspace was loaded from a Definition Bundle, the export preserves useful bundle and selected-entry metadata such as id, version, label, description, and raw ASN.1 source name where possible. Non-selected entries from the loaded bundle are preserved as part of the exported bundle. Generated Definition Bundle files are validated before download; export errors are shown in the Diagnostics pane and API Log.

Hosts can validate external bundle JSON before loading it:

import { parseDefinitionBundleJsonWithDiagnostics } from '@pkistudio/asn1instancebuilder/app';

const result = parseDefinitionBundleJsonWithDiagnostics(bundleJsonText);
if (result.bundle) app.loadBundle(result.bundle);
else console.warn(result.diagnostics);

As of package version 0.1.9, the built-in certificate, certification-request, certificate-list, and pki-bundle bundles carry UI Profiles on their primary entries. Hosts that load them through loadBundle() get improved Form labels, ordering, collapsed PKI sections, placeholders, and input-mode hints automatically. Child sample entries such as TBSCertificate, CertificationRequestInfo, TBSCertList, and AlgorithmIdentifier remain available through the type selector but do not carry those primary-entry profiles.

UI Profile field paths can also use repeated item templates with * for array positions, such as extensions.*.extnID. Exact field paths still take precedence when both an exact path and a template path match.

UI Profiles only describe the input experience. Schema diagnostics, instance diagnostics, and DER generation continue to use the Schema Model and Instance JSON as the source of truth.

The DefinitionBundle, DefinitionBundleDiagnostic, and UiProfile types are host-facing app API contracts from @pkistudio/asn1instancebuilder/app. In the 0.x series they may gain additional optional fields, but existing fields are intended to remain compatible. Bundle version describes the bundle payload format, not the npm package version. Unknown bundle or profile fields are ignored by the current app helpers so hosts can attach private metadata. When both sampleInput and defaultInput are present for an entry type, sampleInput is loaded first; defaultInput is the fallback starting value.

App Instance

The returned app instance exposes:

• build(openViewerWindow?): parse, validate, and build DER from the current UI state. Pass false to suppress opening a standalone viewer window.
• loadBundle(bundle, entryIdOrTypeName?): load a Definition Bundle, optionally selecting an entry by entry id or type name.
• loadSchema(schema): load a Schema Model into the app.
• loadInput(input): load instance input into the app.

Host Boundaries

Host-specific behavior should remain outside the reusable package.

That includes:

• VS Code-specific file access.
• Native dialogs.
• Host persistence.
• Webview lifecycle.
• Policy decisions around where generated DER should be stored or opened.

The browser app currently owns browser file input, clipboard reads, simple definition downloads, local layout persistence, and standalone viewer tab opening for the default web experience.

PkiStudioJS Integration

The app imports PkiStudioJS from the published @pkistudio/pkistudiojs package:

• @pkistudio/pkistudiojs/core.
• @pkistudio/pkistudiojs/oid-resolver.
• @pkistudio/pkistudiojs/viewer.

Generated DER is routed to viewer.html through local storage and displayed in a full PkiStudioJS viewer tab. Hosts that need a different viewer lifecycle can use the Core API directly and own the viewer bridge outside this package.