Skip to content

Basic Concepts ​

PtahJs is a layered low-code engine. Understanding how the core packages fit together makes the runtime and designer APIs much easier to use.

Architecture Overview ​

text
@ptahjs/ui-vue
  Vue integration layer
  components, renderers, bootstrap utilities

@ptahjs/designer
  design-time layer
  commands, history, DnD, editing

@ptahjs/runtime
  runtime layer
  schema compilation, queries, lifecycle chain, hotkeys

@ptahjs/kernel
  core state layer
  IRGraph, change tracking, subscriptions, resources

Kernel ​

@ptahjs/kernel is the lowest-level package. It owns the core state of the DSL tree, also called the IRGraph.

Key responsibilities:

  • Maintain the IRGraph
  • Track state changes with versions
  • Notify subscribers asynchronously
  • Support batch updates
  • Manage the shared resource system

In most cases you use Runtime, not Kernel, directly.


IRGraph ​

The IRGraph is the compiled page structure stored as indexed sections for fast lookup.

SectionDescription
scenesByIdAll scenes by ID
modulesByIdAll modules by ID
childrenIdsByParentIdParent-child relationships
eventsByIdAll events by ID
eventIdsByOwnerIdEvent IDs grouped by owner
sceneIdOrderOrdered scene IDs
subSchemasByIdSub-schema map

When you call runtime.schema(data), the incoming page JSON is compiled into this structure.


Runtime ​

@ptahjs/runtime extends Kernel with business-facing APIs.

  • schema(data) compiles page schema into the IRGraph
  • Query helpers such as getSceneIds(), getSceneById(id), getModuleById(id)
  • Current selection APIs such as setCurrentSceneId() and setCurrentModuleId()
  • lifecycleChain for hook-based processing
  • hotkeys for keyboard shortcuts
js
runtime.schema(pageJson);

const sceneIds = runtime.getSceneIds();
const module = runtime.getModuleById('module-123');
const events = runtime.getOwnerEvents('scene-456');

Designer ​

@ptahjs/designer adds design-time editing on top of Runtime.

  • Command-based edits
  • Undo/redo history
  • Built-in drag and drop
  • Clipboard operations for modules
  • Export through designer.getPageSchema()
js
const moduleId = designer.addModule({
    type: 'UiButton',
    parentId: 'scene-1',
    index: 0,
});

designer.updateModule({
    id: moduleId,
    patch: { props: { label: 'Click me' } },
});

designer.undo();

LifecycleChain ​

runtime.lifecycleChain is a synchronous processing pipeline.

  • Use addStep(type, fn) to register hooks
  • Hooks run in registration order
  • Returning undefined keeps the previous value
js
import { LIFECYCLE_TYPE } from '@ptahjs/kernel';

runtime.lifecycleChain.addStep(LIFECYCLE_TYPE.BEFORE_TRANSFORM_DATA, (schema) => {
    return schema;
});

runtime.lifecycleChain.addStep(LIFECYCLE_TYPE.GET_PAGE_SCHEMA_DATA, (schema) => {
    return schema;
});

Resource System ​

The resource system stores shared configuration such as renderers, module schema maps, and parameter components.

js
import { RESOURCE_TYPE } from '@ptahjs/kernel';

const config = runtime.getResource(RESOURCE_TYPE.RENDERER_CONFIG);

Scene and Module ​

A scene is a top-level page unit. A module is a component instance placed inside a scene or another module.

Typical page structure:

text
Page Schema
- Scene 1
  - UiHeader
  - UiGrid
    - Slot: default
      - UiButton
- Scene 2
- Modal 1

Event Flows ​

In PtahJs, an event is a flow definition rather than a DOM event object. Events belong to a scene or module and are executed by the flow runner.


ui-vue ​

@ptahjs/ui-vue is the Vue integration layer.

  • Bootstrap utilities: useRuntimeApp(), useDesignerApp()
  • Vue plugin: createPtah()
  • Built-in components: Preview, DesignerRoot, ScenesWidget, ModulesWidget, WorkspaceWidget, ParameterWidget, EventsWidget

See the API Reference for details.