@vicin/sigil 1.1.1 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 # Sigil
 
-`Sigil` is a lightweight TypeScript library for creating **nominal identity classes** with compile-time branding and reliable runtime type checks. It organizes classes across your code and gives you power of **nominal typing**, **safe class checks across bundles** and **centralized registry** where reference to every class constructor is stored and enforced to have it's own unique label and symbol.
+`Sigil` is a lightweight TypeScript library for creating **nominal identity classes** with compile-time branding and reliable runtime type checks. It organizes classes across your code and gives you power of **nominal typing**, **safe class checks across bundles** and **centralized registry** where reference to every class constructor is stored and enforced to have its own unique label and symbol.
 
 > **Key ideas:**
 >
@@ -9,11 +9,21 @@
 > - **Inheritance-aware identity**: lineages and sets let you test for subtype/supertype relationships.
 > - **Centralized class registry**: every class have its own unique label and symbol that can be used as an id throughout the codebase.
 
-**Note: You should read these parts before implementing `Sigil` in you code:**
+**Note: You should read these parts before implementing `Sigil` in your code:**
 
-- **Security note:** By default, `Sigil` stores constructor references in the global registry. While it doesn't expose private instance data, it does mean any module can get constructor of the class. if you have sensitive classes that you want to be unaccessable outside it's module update global or per class options (e.g. `updateOptions({ storeConstructor: false })` or `@WithSigil("label", { storeConstructor: false })`). read more [Registery](#registry).
+- **Security note:** By default, `Sigil` stores constructor references in a global registry. While this does not expose private instance data, it allows any module to retrieve a class constructor via its label. If you have sensitive classes that should not be accessible globally, update your options:
 
-- **Performance note:** `Sigil` attaches couple methods to every sigilized class instance, this is negligible in almost all cases, also `.isOfType()` although being reliable and performance optimized but it still less performant that native `instanceof` checks, so if you want maximum performance in cases like hot-path code it is not advised to use `Sigil` as it's built for consistency and maintainability mainly at the cost of minimal performance overhead.
+```ts
+@WithSigil("label", { storeConstructor: false })
+```
+
+See the [Registry](#registry) section for more details.
+
+- **Performance & Hot-Paths note:** `Sigil` attaches minimal metadata to instances, which is negligible for 99% of use cases. While `.isOfType()` is optimized, it is inherently slower than the native `instanceof` operator. For extreme hot-path code where every microsecond counts, stick to native checks—but keep in mind you'll lose Sigil's cross-bundle reliability.
+
+- **HOF & Private Constructors note:** Due to a known TypeScript limitation with class expressions, using HOF helpers (like `withSigilTyped`) on classes with private constructors still allow those classes to be extended in the type system. If strict constructor encapsulation is a priority, please review the [Private Constructors](#private-constructors) guide.
+
+- **Simplified instanceof Replacement:** `Sigil` relies on unique labels to identify classes. If your primary goal is simply to fix `instanceof` across bundles without the overhead of nominal typing or a registry, you can jump straight to our [Minimal Setup Guide](#i-dont-care-about-nominal-types-or-central-registry-i-just-want-a-runtime-replacement-of-instanceof).
 
 ---
 
@@ -24,16 +34,17 @@
   - [Install](#install)
   - [Basic usage (mixin / base class)](#basic-usage-mixin--base-class)
   - [Decorator style](#decorator-style)
-  - [HOF helpers (recommended)](#hof-helpers-recommended)
-  - [Typed helpers (compile-time branding)](#typed-helpers-compile-time-branding)
+  - [HOF helpers](#hof-higher-order-function-helpers)
+  - [Minimal “first-run” example](#minimal-first-run-example)
   - [Migration](#migration)
+- [Limitations & guarantees](#limitations--guarantees)
 - [Core concepts](#core-concepts)
-- [Typing](#typing)
+- [Nominal typing](#nominal-typing)
 - [API reference](#api-reference)
 - [Options & configuration](#options--configuration)
 - [Registry](#registry)
+- [Security guidance](#security-guidance)
 - [Troubleshooting & FAQ](#troubleshooting--faq)
-- [Best practices](#best-practices)
 - [Deprecated API](#deprecated-api)
 - [Phantom](#phantom)
 - [Contributing](#contributing)
@@ -52,7 +63,7 @@
 
 - Easy to use: decorator (`@WithSigil`), mixin (`Sigilify`), and HOF (Higher order function) helpers (`withSigil`, `withSigilTyped`, `typed`).
 
-- **Global registry** to centralize classes (query any class by it's label in run-time) and guard against duplicate labels.
+- **Global registry** to centralize classes (query any class by its label in run-time) and guard against duplicate labels.
 
 - Minimal runtime overhead in production (DEV checks can be toggled off).
 
@@ -70,7 +81,7 @@ yarn add @vicin/sigil
 pnpm add @vicin/sigil
 ```
 
-**Requirements**: TypeScript 5.0+ (for stage-3 decorators) and Node.js 18+ recommended.
+**Requirements**: TypeScript 5.0+ (for stage-3 decorators) and Node.js 18+ recommended. however HOF can be used in older TypeScript versions.
 
 ### Basic usage (mixin / base class)
 
@@ -101,7 +112,7 @@ class User extends Sigil {}
 
 > Note: When extending an already sigilized class (for example `Sigil`), you must decorate the subclass or use the HOF helpers in DEV mode unless you configured the library otherwise.
 
-### HOF (Higher-Order Function) helpers - recommended -
+### HOF (Higher-Order Function) helpers
 
 HOFs work well in many build setups and are idempotent-safe for HMR flows.
 
@@ -115,24 +126,27 @@ const user = new User();
 console.log(User.SigilLabel); // "@myorg/mypkg.User"
 ```
 
-### Typed helpers (compile-time branding)
-
-If you want TypeScript to treat identities nominally (so `UserId` !== `PostId` despite identical shape), use the typed helpers.
+### Minimal “first-run” example
 
 ```ts
-import { Sigil, withSigilTyped, GetInstance } from '@vicin/sigil';
+import { Sigil, withSigil } from '@vicin/sigil';
 
-class _User extends Sigil {}
-const User = withSigilTyped(_User, '@myorg/mypkg.User');
-type User = GetInstance<typeof User>;
+class _User extends Sigil {
+  constructor(public name: string) {
+    super();
+  }
+}
+export const User = withSigil(_User, '@myorg/mypkg.User');
 
-// Now `User` carries a compile-time brand that prevents accidental assignment
-// to other labelled instances with the same structure.
+const u = new User('alice');
+
+console.log(User.SigilLabel); // "@myorg/mypkg.User"
+console.log(User.isOfType(u)); // true
 ```
 
 ### Migration
 
-Migration old code into `Sigil` can be done seamlessly with this set-up:
+Migrating old code into `Sigil` can be done seamlessly with this set-up:
 
 1. Set `SigilOptions.autofillLabels` to `true` at the start of the app so no errors are thrown in the migration stage:
 
@@ -141,7 +155,7 @@ import { updateOptions } from '@vicin/sigil';
 updateOptions({ autofillLabels: true });
 ```
 
-2. Make you base classes extends `Sigil`:
+2. Make your base classes extends `Sigil`:
 
 ```ts
 import { Sigil } from '@vicin/sigil';
@@ -151,11 +165,51 @@ class MyBaseClass {} // original
 class MyBaseClass extends Sigil {} // <-- add 'extends Sigil' here
 ```
 
-Just like this, your entire classes are siglized and you can start using `.isOfType()` as a replacement of `instanceof` in cross bundle checks.
+Just like this, your entire classes are sigilized and you can start using `.isOfType()` as a replacement of `instanceof` in cross bundle checks.
 But there is more to add to your system, which will be discussed in the [Core concepts](#core-concepts).
 
 ---
 
+## Limitations & guarantees
+
+This section states clearly what `Sigil` provides and what it does **not** provide.
+
+### What Sigil guarantees
+
+**1. Stable label → symbol mapping within the same JS global symbol registry.**
+
+- If two bundles share the same **global symbol registry** (the thing `Symbol.for(...)` uses), then `Symbol.for(label)` is identical across them — enabling cross-bundle identity checks when both sides use the same label string.
+
+**2. Reliable runtime identity (when used as intended).**
+
+- When classes are sigilified and their labels are used consistently, `.isOfType()` and the `SigilTypeSet` checks produce stable results across bundles/Hot Module Replacement flows that share the same runtime/global symbol registry.
+
+**3. Optional central registry for discovery & serialization helpers.**
+
+- If enabled, the registry centralizes labels (and optionally constructor references), which can be used for label-based serialization or runtime lookups within a trusted runtime.
+
+**4. Nominal typing that is inheritance-aware**
+
+- With couple extra lines of code you can have nominally typed classes.
+
+### What Sigil does not guarantee
+
+**2. It is not for across isolated JS realms.**
+
+Examples of isolated realms where Sigil may not work as expected:
+
+- iframe with a different global context that does not share the same window (and therefore a different symbol registry).
+- Workers or processes that do not share the same `globalThis` / symbol registry.
+- Cross-origin frames where symbols are not shared.
+
+In such cases you must provide a bridging/serialization protocol that maps labels to constructors on each side. however `Sigil` if used as intended makes serialization protocol much easier as each class will have a unique label.
+
+**3. Not a security or access-control mechanism.**
+
+Presence of a constructor or label in the registry is discoverable (unless you purposely set `storeConstructor: false`). Do **not** use `Sigil` as an authorization or secrets mechanism.
+
+---
+
 ## Core concepts
 
 ### Terminology
@@ -216,12 +270,11 @@ The goal is simple:
 
 #### Problem A — `instanceof` is unreliable
 
-**Sigil’s solution (runtime chain).**
-To make runtime identity reliable across bundles, HMR, and transpiled code, `Sigil` explicitly attaches identity metadata and tracks inheritance lineage on classes. That tracking starts with a contract created by `Sigilify()` (a mixin / class factory) or by extending the `Sigil` base class. Sigilify augments a plain JS class with the metadata and helper methods Sigil needs (for example, `isOfType`).
+To make runtime identity reliable across bundles, HMR, and transpiled code, `Sigil` explicitly attaches identity metadata and tracks inheritance lineage on classes. That tracking starts with a contract created by `Sigilify()` (a mixin) or by extending the `Sigil` base class. Sigilify augments a plain JS class with the metadata and helper methods Sigil needs (for example, `isOfType`).
 
 Basic patterns:
 
-Mixin / factory:
+**Mixin:**
 
 ```ts
 import { Sigilify } from '@vicin/sigil';
@@ -229,27 +282,27 @@ import { Sigilify } from '@vicin/sigil';
 const MyClass = Sigilify(class {}, 'MyClass');
 ```
 
-Direct base-class extend:
+**Direct base-class extend:**
 
 ```ts
 import { Sigil, WithSigil } from '@vicin/sigil';
 
+@WithSigil('MyClass')
 class MyClass extends Sigil {}
 ```
 
-**Enforced contract.**
-Once you opt into the runtime contract, Sigil enforces consistency: in DEV mode, extending a sigil-aware class without using decorator `@WithSigil` or a provided HOF (e.g. `withSigil` or `withSigilTyped`) will throw a helpful error. If you prefer a laxer setup, Sigil can be configured to auto-label or disable the strict enforcement.
+Once you opt into the runtime contract, Sigil enforces consistency: in DEV mode, extending a sigil-aware class without using decorator `@WithSigil` or a provided HOF (e.g. `withSigil` or `withSigilTyped`) will throw a helpful error. If you prefer a laxer setup, Sigil can be configured to auto-label.
 
-Decorator style:
+**Decorator:**
 
 ```ts
 import { Sigil, WithSigil } from '@vicin/sigil';
 
-@WithSigil('MyClass') // <-- Note `@WithSigil` used here cause it extended alreay sigilized class (Sigil). Error is thrown without it.
+@WithSigil('MyClass')
 class MyClass extends Sigil {}
 ```
 
-HOF (preferred for many workflows):
+**HOF:**
 
 ```ts
 import { Sigil, withSigil } from '@vicin/sigil';
@@ -258,17 +311,22 @@ class _MyClass extends Sigil {}
 const MyClass = withSigil(_MyClass, 'MyClass');
 ```
 
-Recommendation:
+#### Problem B — Branding can get messy
 
-- Use the decorator approach for a minimal, runtime-only fix for `instanceof`.
-- Use the HOFs when you want better ergonomics or plan to opt into typed branding later.
+Runtime metadata alone does not change TypeScript types. To get compile-time nominal typing (so `UserId` ≠ `PostId` even with the same shape), Sigil provides two patterns:
 
-#### Problem B — manual branding
+**Decorator with brand field:**
 
-**Sigil’s solution (typed chain).**
-Runtime metadata alone does not change TypeScript types. To get compile-time nominal typing (so `UserId` ≠ `PostId` even with the same shape), Sigil provides typed HOFs that produce TypeScript-branded classes while preserving runtime metadata.
+```ts
+import { Sigil, WithSigil, UpdateSigilBrand } from '@vicin/sigil';
 
-Example using a typed HOF:
+@WithSigil('User')
+class User extends Sigil {
+  declare __SIGIL_BRAND__: UpdateSigilBrand<'User', Sigil>; // <-- inject type
+}
+```
+
+**HOF with `_Class` / `Class`:**
 
 ```ts
 import { Sigil, withSigilTyped, GetInstance } from '@vicin/sigil';
@@ -281,76 +339,47 @@ const User = withSigilTyped(_User, 'User');
 type User = GetInstance<typeof User>;
 ```
 
-With the typed HOF:
-
-- The emitted runtime class still has sigil metadata (symbols, lineage).
-- The TypeScript type for the class is narrowed to the `UserId` label at compile time. Assignments between different labels become type errors.
-
----
-
-#### Why there are '\_Class' and 'Class'
-
-The typed approach requires redefinition of public class, so you have:
-
-- **Untyped class:** `_User` — regular class code used for inheritance and implementation.
-- **Typed class:** `User` — the result of the typed HOF; this is the sigil-aware, branded class used by the rest of your codebase.
-
-This separation is necessary as typescript decorators doesn't affect type system. so to reflect type update the class should be passed to HOF.
-
-Example of approach for class chain:
+Typings are lineage aware as well:
 
 ```ts
 import { Sigil, withSigilTyped, GetInstance } from '@vicin/sigil';
 
-// Untyped base classes used for implementation:
-class _User extends Sigil {}
+class _A extends Sigil {}
+const A = withSigilTyped(_A, 'A');
+type A = GetInstance<typeof A>;
 
-const User = withSigilTyped(_User, 'User');
-type User = GetInstance<typeof User>;
-
-class _Admin extends User {}
+class _B extends A {}
+const B = withSigilTyped(_B, 'B');
+type B = GetInstance<typeof B>;
 
-const Admin = withSigilTyped(_Admin, 'Admin');
-type Admin = GetInstance<typeof Admin>;
-
-// Type relationships:
-type test1 = User extends Admin ? true : false; // false
-type test2 = Admin extends User ? true : false; // true
+type test1 = A extends B ? true : false; // false
+type test2 = B extends A ? true : false; // true
 ```
 
-This demonstrates:
-
-- `Admin` is recognized as a subtype of `User` (both at runtime and in types) if it was created via the appropriate typed helpers.
-
----
-
 #### SigilLabel & SigilType
 
 If library is used with default options, `SigilLabel` & `SigilType` are **100% unique** for each class, which make them perfect replacement of manual labeling across your code that comes shipped with Sigil by default. you can access them in class constructor directly of via `getSigilLabel()` and `getSigilType()` in instances.
 
 ---
 
-## Typing
+## Nominal typing
 
 In this part we will discuss conventions to avoid any type errors and have normal developing experience with just extra few definition lines at the bottom of the file.
+First we have two patterns, **HOF with `_Class` / `Class`** and **Decorators with brand field**:
 
----
-
-### Typed vs Untyped classes
-
-The update of Sigil brand types happens via HOF that are defined below actual class definition.
+### HOF with `_Class` / `Class`
 
-Example:
+The update of `Sigil` brand types happens via HOF that are defined below actual class definition:
 
 ```ts
-import { Sigil, withSigilTyped } from '@vicin/sigil';
+import { Sigil, withSigilTyped, GetInstance } from '@vicin/sigil';
 
 class _X extends Sigil {
   // All logic for class
 }
 
 export const X = withSigilTyped(_X, 'Label.X'); // <-- Pass class with label to uniquely identify it from other classes
-export type X = InstanceType<typeof X>; // alias to instance to avoid InstanceType<typeof X> everywhere
+export type X = GetInstance<typeof X>;
 ```
 
 In other parts of the code:
@@ -363,17 +392,14 @@ class _Y extends X {
 }
 
 export const Y = withSigilTyped(_Y, 'Label.Y');
-export type Y = InstanceType<typeof Y>;
+export type Y = GetInstance<typeof Y>;
 ```
 
 So as we have seen nominal identity is introduced with few lines only below each class. and the bulk code where logic lives is untouched.
 
----
-
-### `InstanceType<>` vs `GetInstance<>`
+#### `InstanceType<>` vs `GetInstance<>`
 
-Earlier example used `InstanceType<>` to get instance of the class. It works well until class constructor is `protected` or `private` which cause it to return `any`.
-So alternative in introduced which is `GetInstance`.
+You should depend on `GetInstance` to get type of instance and avoid using `InstanceType` as it returns `any` if the class constructor is `protected` or `private`.
 
 ```ts
 import { Sigil, withSigilTyped, GetInstance } from '@vicin/sigil';
@@ -381,14 +407,12 @@ import { Sigil, withSigilTyped, GetInstance } from '@vicin/sigil';
 class _X extends Sigil {}
 
 export const X = withSigilTyped(_X, 'Label.X');
-export type X = GetInstance<typeof X>; // <-- Just replace 'InstanceType' here with 'GetInstance'
+export type X = GetInstance<typeof X>; // <-- works with 'private' and 'protected' constructors as well
 ```
 
-Internally `GetInstance` is just `T extends { prototype: infer R }` with appending new `__SIGIL_BRAND__` to it.
-
----
+Internally `GetInstance` is just `T extends { prototype: infer R }`.
 
-### Generic propagation
+#### Generic propagation
 
 One of the downsides of defining typed class at the bottom is that we need to redefine generics as well in the type.
 
@@ -404,9 +428,7 @@ export const X = withSigilTyped(_X, 'Label.X');
 export type X<G> = GetInstance<typeof X<G>>; // <-- Generics re-defined here, just copy-paste and pass them
 ```
 
----
-
-### Anonymous classes
+#### Anonymous classes
 
 You may see error: `Property 'x' of exported anonymous class type may not be private or protected.`, although this is rare to occur.
 This comes from the fact that all typed classes are `anonymous class` as they are return of HOF and ts compiler struggle to type them safely. to avoid these error entirely all you need is exporting the untyped classes even if they are un-used as a good convention.
@@ -420,6 +442,61 @@ export const X = withSigilTyped(_X, 'Label.X');
 export type X = GetInstance<typeof X>;
 ```
 
+#### Private constructors
+
+The only limitation in HOF approach is **extending private constructors**:
+
+```ts
+import { Sigil, withSigilTyped, GetInstance } from '@vicin/sigil';
+class _X extends Sigil {
+  private constructor() {}
+}
+const X = withSigilTyped(_X, 'X');
+type X = GetInstance<typeof X>;
+
+class _Y extends X {} // <-- This is allowed!
+const Y = withSigilTyped(_Y, 'Y');
+type Y = GetInstance<typeof Y>;
+
+const y = new Y(); // <-- Type here is any
+```
+
+Unfortunately this is a limitation in typescript and i couldn't find any solution to adress it.
+
+---
+
+### Decorators with brand field
+
+The update of `Sigil` brand type happens directly by overriding `__SIGIL_BRAND__` field:
+
+```ts
+import { Sigil, WithSigil, UpdateSigilBrand } from '@vicin/sigil';
+
+@WithSigil('X')
+class X extends Sigil {
+  declare __SIGIL_BRAND__: UpdateSigilBrand<'X', Sigil>;
+}
+
+@WithSigil('Y')
+class Y extends X {
+  declare __SIGIL_BRAND__: UpdateSigilBrand<'Y', Sigil>;
+}
+```
+
+As you see no `_Class`/`Class` pattern, no `private constructor` issue and no type hacks, but our branding logic now lives in class body.
+
+To be more explicit and prevent mismatch between run-time and compile-time labels we can:
+
+```ts
+import { Sigil, WithSigil, UpdateSigilBrand } from '@vicin/sigil';
+
+const label = 'X';
+@WithSigil(label)
+class X extends Sigil {
+  declare __SIGIL_BRAND__: UpdateSigilBrand<typeof label, Sigil>;
+}
+```
+
 ---
 
 ## API reference
@@ -433,7 +510,7 @@ Top-level exports from the library:
 ```ts
 export { Sigil, SigilError } from './classes';
 export { WithSigil } from './decorator';
-export { typed, withSigil, withSigilTyped } from './enhancers';
+export { withSigil, withSigilTyped } from './enhancers';
 export {
   isDecorated,
   isInheritanceChecked,
@@ -451,12 +528,11 @@ export {
 } from './options';
 export type {
   ISigil,
-  ISigilInstance,
-  ISigilStatic,
   TypedSigil,
   GetInstance,
   SigilBrandOf,
   SigilOptions,
+  UpdateSigilBrand,
 } from './types';
 ```
 
@@ -468,13 +544,12 @@ export type {
 - `Sigilify(Base, label?, opts?)`: mixin function that returns a new constructor with sigil types and instance helpers.
 - `withSigil(Class, label?, opts?)`: HOF that validates and decorates an existing class constructor.
 - `withSigilTyped(Class, label?, opts?)`: like `withSigil` but narrows the TypeScript type to include brands.
-- `typed(Class, label?, parent?)`: type-only narrowing helper (no runtime mutation) — asserts runtime label in DEV.
 - `isSigilCtor(value)`: `true` if `value` is a sigil constructor.
 - `isSigilInstance(value)`: `true` if `value` is an instance of a sigil constructor.
 - `SigilRegistry`: `Sigil` Registy class used to centralize classes across app.
 - `getActiveRegistry`: Getter of active registry being used by `Sigil`.
 - `updateOptions(opts, mergeRegistries?)`: change global runtime options before sigil decoration (e.g., `autofillLabels`, `devMarker`, etc.).
-- `DEFAULT_LABEL_REGEX`: regex that insures structure of `@scope/package.ClassName` to all labels, it's advised to use it as your `SigilOptions.labelValidation`
+- `DEFAULT_LABEL_REGEX`: regex that ensures structure of `@scope/package.ClassName` to all labels, it's advised to use it as your `SigilOptions.labelValidation`
 
 ### Instance & static helpers provided by Sigilified constructors
 
@@ -510,29 +585,20 @@ updateOptions({
   autofillLabels: false, // auto-generate labels for subclasses that would otherwise inherit
   skipLabelInheritanceCheck: false, // skip DEV-only inheritance checks -- ALMOST NEVER WANT TO SET THIS TO TRUE, Use 'autofillLabels: true' instead. --
   labelValidation: null, // or a RegExp / function to validate labels
-  devMarker: process.env.NODE_ENV !== 'production', // boolean used to block dev only checks in non-dev enviroments
+  devMarker: process.env.NODE_ENV !== 'production', // boolean used to block dev only checks in non-dev environments
   registry: new SigilRegistry(), // setting active registry used by 'Sigil'
-  useGlobalRegistry: true, // append registry into 'globalThis' to insure single source in the runtime in cross bundles.
+  useGlobalRegistry: true, // append registry into 'globalThis' to ensure single source in the runtime in cross bundles.
   storeConstructor: true, // store reference of the constructor in registry
 });
 ```
 
 Global options can be overridden per class by `opts` field in decorator and HOF.
 
-**Notes**:
-
-- It's advised to use `updateOptions({ labelValidation: DEFAULT_LABEL_REGEX })` at app entry point to validate labels against `@scope/package.ClassName` structure.
-- `devMarker` drives DEV-only checks — when `false`, many runtime validations are no-ops (useful for production builds).
-- `autofillLabels` is useful for some HMR/test setups where you prefer not to throw on collisions and want autogenerated labels.
-- `skipLabelInheritanceCheck = true` can result on subtle bugs if enabled, so avoid setting it to true.
-- When `SigilOptions.registry` is updated, old registry entries is merged and registered into new registry, to disable this behavrio pass `false` to `mergeRegistries` (`updateOptions({ registry: newRegistry }, false)`)
-- `useGlobalRegistry` makes Sigil registry a central manager of classes and reliable way to enforce single label usage, so avoid setting it to `false` except if you have a strong reason. if you want to avoid making class constructor accessible via `globalThis` use `storeConstructor = true` instead.
-
 ---
 
 ## Registry
 
-`Sigil` with default options forces devs to `SigilLabel` every class defined, that allows central class registery that store a reference for every class keyed by its label, also it prevent two classes in the codebase from having the same `SigilLabel`.
+`Sigil`'s default options require developers to label every class, that allows central class registry that stores a reference for every class keyed by its label, also it prevent two classes in the codebase from having the same `SigilLabel`.
 
 This is mainly useful in large codebases or frameworks where they need central registry or if you need class transport across API, workers, etc... where you can use `SigilLabel` reliably to serialize class identity. to interact with registry `Sigil` exposes `getActiveRegistry` and `SigilRegistry` class. also you can update registry related options with `updateOptions`.
 
@@ -584,8 +650,8 @@ import { updateOptions } from '@vicin/sigil';
 updateOptions({ useGlobalRegistry: false });
 ```
 
-Before applying this change, for registry to function normally you should insure that `Sigil` is not bundles twice in your app.
-however if you can't insure that only bundle of `Sigil` is used and don't want class constructors to be accessible globally do this:
+Before applying this change, for registry to function normally you should ensure that `Sigil` is not bundles twice in your app.
+however if you can't ensure that only bundle of `Sigil` is used and don't want class constructors to be accessible globally do this:
 
 ```ts
 import { updateOptions } from '@vicin/sigil';
@@ -606,7 +672,7 @@ Pick whatever pattern you like!
 
 ### Class typing in registry
 
-Unfortunately concrete types of classes is not supported and all classes are stored as `ISigil` type. if you want concrete typings you can wrap registery:
+Unfortunately concrete types of classes is not supported and all classes are stored as `ISigil` type. if you want concrete typings you can wrap registry:
 
 ```ts
 import { getActiveRegistry } from '@vicin/sigil';
@@ -670,7 +736,48 @@ Z.isOfType(new X()); // true
 Y.isOfType(new Y()); // false
 ```
 
-No class constructors are stored globally and no code overhead, moreover if you can insure that `Sigil` is not bundles twice you can disable `useGlobalRegistry` and no trace of sigil in `globalThis`.
+No class constructors are stored globally and no code overhead, moreover if you can ensure that `Sigil` is not bundles twice you can disable `useGlobalRegistry` and no trace of sigil in `globalThis`.
+
+---
+
+## Security guidance
+
+### Recommended defaults & quick rules
+
+- Default recommendation for public/shared runtimes (web pages, untrusted workers, serverless):
+
+```ts
+updateOptions({ useGlobalRegistry: false, storeConstructor: false });
+```
+
+This prevents constructors from being put on `globalThis` and prevents constructors from being stored in the registry map (labels remain, but constructors are `null`).
+
+- For private server runtimes (single controlled Node process) where a central registry is desired:
+
+```ts
+updateOptions({ useGlobalRegistry: true, storeConstructor: true });
+```
+
+Only enable this if you control all bundles and trust the runtime environment.
+
+### Per-class sensitivity control
+
+If you want the registry in general but need to hide particular classes (e.g., internal or security-sensitive classes), pass `storeConstructor: false` for those classes:
+
+```ts
+class _Sensitive extends Sigil {}
+export const Sensitive = withSigil(_Sensitive, '@myorg/internal.Sensitive', {
+  storeConstructor: false, // label kept, constructor not stored
+});
+```
+
+This keeps the declarative identity but avoids exposing the constructor reference in the registry.
+
+### Short warnings (do not rely on Sigil for)
+
+- **Not a security boundary:** Registry labels/constructors are discovery metadata — do not put secrets or private instance data in them or rely on them for access control.
+
+- **Third-party code can access the registry if `useGlobalRegistry: true`** — only enable that in fully trusted runtimes.
 
 ---
 
@@ -688,13 +795,9 @@ A: Use `@WithSigil("@your/label")`, or wrap the subclass with `withSigil` / `wit
 
 A: This error comes from the fact that all typed classes (return from `withSigil`, `withSigilTyped` or `typed`) are 'anonymous class' as they are the return of HOF. all you need to do is to export untyped classes (`_Class`) that have private or protected properties. or even export all untyped classes as a good convention even if they are not used.
 
-**Q: I need nominal types in TypeScript. Which helper do I use?**
-
-A: Use `withSigilTyped` to both attach runtime metadata and apply compile-time brands. If runtime metadata already exists and you only want to narrow types, use `typed(...)` (which is type-only but asserts the runtime label in DEV).
-
 **Q: How do I inspect currently registered labels?**
 
-A: Use `getActiveRegistry()?.list()` to get an array of registered labels.
+A: Use `getActiveRegistry()?.listLabels()` to get an array of registered labels.
 
 **Q: What if i want to omit labeling in some classes while enforce others?**
 
@@ -702,15 +805,6 @@ A: You can set `SigilOptions.autofillLabels` to `true`. or if you more strict en
 
 ---
 
-## Best practices
-
-- Prefer `withSigil`/`withSigilTyped` for predictable, explicit decoration.
-- Keep labels globally unique and descriptive (including scope and package like `@myorg/mypkg.ClassName`).
-- Use typed helpers for domain-level identities (IDs, tokens, domain types) so the compiler helps you avoid mistakes.
-- Run with `devMarker` enabled during local development / CI to catch label collisions early.
-
----
-
 ## Deprecated API
 
 ### REGISTRY
@@ -739,6 +833,10 @@ const newRegistry = new SigilRegistry(); // can pass external map to constructor
 updateOptions({ registry: newRegistry });
 ```
 
+### typed
+
+Typed was added to add types to output from `Sigilify` mixin, but now mixin do this by default.
+
 ---
 
 ## Phantom